Documentation and Naming

Transcription

1 Authors: Michael Seubert Thilo Krähmer Semantics 3 Definition 2 Abstraction 4 Term Building Scoping & Understanding 1 Topic enterprise SOA Object & Service Operation Design Part V of VI Documentation and Naming Guideline Version 2.7 February 27th, 2009 I Documentation and Naming

2 Authors Name Seubert, Michael Krähmer, Thilo Role Author Author

3 Table of Contents I Documentation and Naming... 1 Guide to Readers Introduction Definition Standards for Definition Aspects of a Definition Definition Comment Structure Use Integrity Condition Constraint Restriction Example Note Overview of SAP Modeling Entities and their used Aspects Definition Pattern for SAP Modeling Entities Term Standards for Term Scope Authority Semantic Rules Syntactic Rules Lexical Rules Uniqueness Rules Clarification of Terms The Semantic Triangle Synonyms Homonyms Equipollence Vagueness Imprecise Usage Reconstructing Terms Establishing Terms Linkage of Terms Aggregation of Terms Generalization of Terms Page 3 of 113

4 Eliminating Linguistic Defects Pattern Terminological Patterns Grouping Together and Dividing Up Version and Variant Catalogue Structure Patterns Hierarchy and Net Relationship Item Assignment Determination Business Patterns Business Transaction Documents Naming Rules for Model Entities Naming Rule Notation Semantic Name and Technical Name Object Object Template Object Node Specialization Node Grouped Object Node Dependent Object Inclusion Node Transformation Node Relationship Composition Aggregation / Association Association for Navigation Filtered Association for Navigation Structure Relationships Hierarchy Relationship Without Attributes Hierarchy Relationship With Attributes Net Relationship With or Without Attributes Cross References within Same Level Data Type Node Data Type Intermediate Data Type Filter Data Type Key Data Type IDT replacing a GDT Including Keys instead of IDs Action Data Type Query Data Type Query Intermediate Data Type Extension Data Type Data Type Element...70 Page 4 of 113

5 4.7.1 Elements of a Node Data Type Aggregated Status Element Element Typed by Key Elements of a Key Data Type Action Data Type Element Query Data Type Element Core Service Operation Action Query Compound Service Operation Service View Service Interface Service Operation (Asynchronous) Service Operation (Synchronous) Service Operation (A2X) Message Type Message Data Type Message Intermediate Data Type / Element within a Message Data Type Response View Query / Response - Service Operation Query / Response - Message Type Query / Response - Message Data Type Mass Messages Reconciliation Messages Form and Interactive Form Create With Reference (A2X) SAP Abbreviation Rules SAP Abbreviations Guiding Principles General Abbreviation Rules Abbreviations in ARIS - Names and Length Restrictions ARIS Name - Abbreviation Rules ARIS Technical Name - Length Restrictions Overview ARIS Technical Name: Abbreviation Rules ESR Name Adopted from ARIS Technical Name SAP Object Model - Documentation Target Group Specific Pattern-Based Documentation Hints for Object Definition Paragraph Structure Hints for Object Node Definition Object Root Node Page 5 of 113

6 6.4 Hints for Object Node Element Definition Index Change History Page 6 of 113

7 Guide to Readers This part describes how a real-world entity, in particular an object of the SAP object model, is to be found and documented. This covers the abstraction of real world -concepts, rules for its definition and the finding of a term for its corresponding model entity. It is shown what kinds of problems may occur and how to solve them. Naming patterns are described and hints for defining and naming of dedicated entities are given. Naming rules for the respective model entities are specified as well as abbreviation rules needed to fulfill length restrictions of the modeling tool and implementation environment. The underlying concepts are not contained within this document. Nevertheless their understanding is a prerequisite for understanding this document. Regarding the concepts refer to the corresponding guidelines. Page 7 of 113

8

9 1 Introduction Object-orientation reflects the general human thinking: To understand a topic in the real world, each perception is classified or categorized. This step is called abstraction. The abstract concept needs a definition reflecting its semantics. From this definition, a commonly understandable term is derived. This term has to represent the definition. Semantics 3 Definition 2 Abstraction 4 Term Building Scoping & Understanding 1 Topic Figure 1: Understanding the world The goal of this document is to enable the reader to create a business-oriented, comprehensive documentation of entities such as business objects. That is: One document for different target groups with different granularity Page 9 of 113

10 Why? Its all about business Clear definition of business concepts Transparent business semantics for everybody For whom? Developers Partners Consultants Independent Software Vendors Customers How to achieve this? Differentiated Terms - Clear Definition is Key The language we use to some extent determines the way in which we view and think about the world around us (Sapir-Whorf Hypothesis) For example, Eskimos have more than 50 terms for snow - well defined and clearly separated from each other. That means their language is much more differentiated in that area then for example the German language. That means clear definition of business concepts is the basis to a Clear understanding of the real world Clear differentiation between objects Page 10 of 113

11 Examples for business terms Activity Opportunity Lead Purchase Requirement Purchase Request Purchase Order Sales Order But what is their semantics? How to find and define an object? Get a clear understanding: selective, precise, specific, detailed Define the capsule: That is, find the border o o Inside / outside of the object What does belong to the object, what does not? (the car?; the tree?, the house?, the window?) Distinction and separation from other objects This is the basis for the definition. Page 11 of 113

12

13 2 Definition 2.1 Standards for Definition SAP Definitions follow the ISO rules and guidelines ISO specifies (amongst others) requirements and recommendations for constructing definitions for data and metadata. semantic aspects of definitions are addressed. For details see ISO/IEC (Formulation of data definitions) ISO contains the following requirements and recommendations for a definition: Requirements: A data definition shall: a) be stated in the singular b) state what the concept is, not only what it is not c) be stated as a descriptive phrase or sentence(s) d) contain only commonly understood abbreviations e) be expressed without embedding definitions of other data or underlying concepts Recommendations: A data definition should: a) state the essential meaning of the concept b) be precise and unambiguous c) be concise d) be able to stand alone e) be expressed without embedding rationale, functional usage, domain information, or procedural information f) avoid circular reasoning g) use the same terminology and consistent logical structure for related definitions h) be appropriate for the type of metadata item being defined These requirements and recommendations are detailed in the following aspects of a definition. Page 13 of 113

14 2.2 Aspects of a Definition There are different types of information for the description of an object / entity. These aspects are described in the following paragraphs. For the development of a definition it is useful to clearly separate these aspects. In ARIS they are separated by using an individual ARIS attribute for each aspect Definition Definition is a description of the particular set of business-related facts that is delimited in an object. A definition fulfils the following criteria: Semantics Sufficient Abstract / Concrete Necessary Differentiating Outside-In Integrity Syntax The object is described from a semantical, business-oriented point of view. ( An object is ). The definition covers the target scope; restrictions are specified separately. Use business terms only; avoid technical / modeling terms such as node. All differentiating description elements are contained and the relation between them is clear As concrete as possible, abstract where necessary No additional information is contained, such as examples, comments, paraphrases etc. The unique selling point of SAP becomes apparent, if such exists. The terminology corresponds to the language and terms used in books or standards of the corresponding area of expertise, including the semantics specified by them. Not contradictory, only supplementary / more restrictive. For a term used in a definition a definition has to be available. It can be defined in the object model, be commonly understandable or be defined in the comment section. The relation between the individual terms must be clear. For example use term Bidder if you mean the Party Role Bidder. Do not create homonyms. Start every definition with the super ordinate term to which it belongs. Use an article at the start of the definition. Example sales order: A request from a customer to a seller to deliver materials and provide the relevant services at a specific time. Page 14 of 113

15 In the daily work of defining entities, the following difficulties or problems may occur. The Definition Enemies Different definitions (and different terms) for the same business concept in the real world (Redundancy) Different terms for identical information / content / definition (Synonyms) Identical terms for different information / content / definition (Homonyms) See also the description of linguistic defects and their clarification in section 3.2, page Comment Comment is the reference to the environment of a term, as well as the definitions of terms used in the definition that are not in common use, and which are not already defined by other business objects Structure Structure is a general description of the entity types grouped by the defined object. It describes the business-related environment of the object. The general description can also be accompanied by a specific example (if necessary, with weighting) if a complete description cannot be provided. In case of a business object it explains the meaning of its major nodes, from a business perspective Use Use is a specification of possible usages of the entity (context) Integrity Condition Integrity condition is the condition that ensures the consistency and completeness of an entity from a business point of view. The condition incorporates the entity, its subordinate entities and its relationships to other entities and describes their dependencies to each other. For example only one of the relationships A and B may exist. Page 15 of 113

16 2.2.6 Constraint Constraint is the limitation of an entity from a business point of view. For example data type elements typed by a code-gdt where only some code values are allowed Restriction Restriction is the limitation of the planned scope of an entity specified in its definition. In distinction to constraint this limitation is only valid at the moment; the full scope specified will be available in future. This is necessary because the documentation is legally binding. Examples: A business object does not provide the full defined scope at the moment. The current limitations are specified in this section. An operation does not support the full structure of a message type. The structures and fields of the message type that are not (yet) covered by the operation are specified in this section. This can be the case especially for older message types Example Example is an instance of the entity. It should cover the full complexity of the entity. If there are different kinds of instances, provide an instance for each kind Note Note is a description of special properties of the entity. They cover information that is not businessrelated but useful from a technical point of view. For example, for a GDT the reference to its corresponding R/3 data type may be specified. Page 16 of 113

17 2.3 Overview of SAP Modeling Entities and their used Aspects The following table lists for several AP model entities the used definition aspects. Object / Node Relationship Core Service Global Data Type (GDT) Name / Definition Aspect BO BO Node Node Data type Node Data Type Element Key Data Type Key Data Type Element Generalization Type Composition Aggregation Association Filter Data Type Filter Data Type Element Action Action Data Type Action Data Type Element Query Query Data Type Query Data Type Element GDT Attribute GDT Element Code List Code Qualifier List Qualifier Name m m m m m m m m m m m m m m m m m m m m m m m m m Definition m m m m m m m o m o m o m m m m m Comment o o o o o o o o o o o o o o o Structure m Use o o o m o Integrity Condition o o o o o o o o m o Constraint o Restriction o Note o o m o Example o o m Figure 2: Definition Aspects used by Model Entities Legend: m o mandatory optional 2.4 Definition Pattern for SAP Modeling Entities To ensure a common form of SAP modelling entity definitions, patterns are defined for each of them. You can find the definition pattern on the Wiki page of of AP KM Standards & Guidelines (S&G): (S&G for Terminology and Glossary Definitions) Page 17 of 113

18

19 3 Term 3.1 Standards for Term SAP terms are built according to ISO According to ISO the following aspects are to be prescribed: The scope of the naming convention, e.g. an industry The authority that establishes the naming conventions Semantic rules governing the source and content of the terms used in a name, e.g. terms derived from data models, terms commonly used in the discipline, etc. Syntactic rules covering required term order Lexical rules covering controlled term lists, name length, character set, language A rule establishing whether or not names must be unique For details see ISO/IEC (Naming and identification principles for data elements). The term conventions valid for all entities of the SAP object model are specified in the following sections. The term conventions that are specific for an entity are described in the respective naming rule section for this entity Scope The scope covers all entities of the SAP object model including the entities Object (BO, TecO...) Object node (TN, RTN ) Relationship (composition, aggregation ) Service (action, query, service interface, service operation ) Data type (GDT, IDT ) Data type element (NDT-element, status-element ) Authority The term conventions are established by the corresponding PIC Coaching Teams in cooperation with the Business Object Task Force (BOT) and the Service Definition Methodology Council (SDMC). Page 19 of 113

20 3.1.3 Semantic Rules The semantic rules follow the ebxml CCTS, which is based on ISO/IEC Qualifier Object Class Qualifier Property Qualifier Representation Figure 3: Naming Parts of an Entity Name according to ISO/IEC A term is made up of three parts: The object class : A set of concepts, abstractions or things in the real world which can be identified within clear boundaries and meanings, and whose characteristics and behavior follow the same rules (examples: automobile, person, household, order...). The property : A characteristic feature shared by all the instances of an object class (examples: color, age, income, address...). The representation : Describes how the data is represented, meaning the data type and its value range (examples: a date can be represented with xsd:date or xsd:datetime). Each of these three name components can be semantically restricted by one or several qualifiers. The order of the qualifier is not significant. Qualifiers are needed to make a term unique within a specified context. Page 20 of 113

21 3.1.4 Syntactic Rules a) Object class terms shall occupy the first (leftmost) position in the name. b) Qualifier terms shall precede the part qualified. The order of qualifiers shall not be used to differentiate terms. If the qualifier is an established term of its own and contains the semantics of the term qualified, the qualified term is omitted. Example: Qualifier Approver describes an object Employee in more detail. As approver is an established term and an approver is always an employee the resulting name is Approver (and not Approver Employee ) c) The property term shall occupy the next position. d) The representation term shall occupy the last position. If the representation term is redundant with the latter part of the property term, one occurrence will be deleted Lexical Rules a) Terms are in singular form only, except the entity itself is plural. b) Terms are in Title Case. Exceptions: Data Types, Data Type Elements, Codes and Code lists are in UpperCamel- Case. See chapter 4.2, page 48. Attributes are in lowercamelcase. See chapter 4.2, page 48. A Data Type can have a variable as prefix followed by an underscore such as SHORT_, MEDIUM_ and LONG_. The variable contains upper case letters only. c) Abbreviations, acronyms, and initialisms are allowed only when used normally within business terms (for this, see Oxford Dictionary). Exceptions: UUID - Universally Unique Identifier URI - Unified Resource Identifier PO Box Post Office Box SAP - Systems Applications and Products in Data Processing IT Control - Information Technology Control RFI - Request for Information Abbreviations for countries contained in the code list of GDT CountryCode (restricted use for country specific objects and extensions) d) Words contain letters only. Exceptions: An template-object contains an underscore that separates the suffix Template Country specific objects and extensions contain underscore behind the country code. A GDT can contain an underscore to separate a variable as prefix. For versioning an underscore is used to separate the version as suffix e) The technical name for a term is in UpperCamelCase. See chapter 4.2, page 48. Page 21 of 113

22 3.1.6 Uniqueness Rules The context in which a term has to be unique depends on the entity that is named by the term. Figure 4 shows an overview about the uniqueness rules for the respective model entities. Object / Node / Relationship Service Data Type Entity Object Object Node Composition Inbound Aggregation, Inbound Association Association for Navigation Action, Query Service Interface Service Operation Message Type Data Type Supplementary Component (SC) Data Type Element Code List Code Qualifier Uniqueness Context SAP wide Object the node belongs to Source node Target node Source node Node the action / query belongs to SAP wide Service interface SAP wide SAP wide Data type the SC belongs to Data type the element belongs to SAP wide Code list the code belongs to Data type the qualifier belongs to Figure 4: Uniqueness Rules for Model Entities The required uniqueness of a term is, as a rule, ensured by the specific naming conventions for the respective entity. Page 22 of 113

23 3.2 Clarification of Terms To allow communication about a set of facts (here models), terms must be used in a uniform manner. Therefore, as a first step in modelling, an understanding must be reached concerning the terms to be used. Figure 5: Discussion of Terms The terms obtained from a survey are analyzed and synonyms and homonyms are eliminated. Page 23 of 113

24 3.2.1 The Semantic Triangle For the definition of a term, the semantic triangle - a schema borrowed from linguistics - is used. In this triangle, the definition of a term is established by means of an extension, an intension and a sign. Figure 6: The Semantic Triangle A term is clearly and uniquely defined when the sign, the intension and the extension are in concordance. Sign: Intension: Extension: Name of a term Meaning of a term, described by its characteristics Scope of meaning of a term, semantic field / business area. Description of the field / business area or object to which a term relates. Example: In the field of business administration the term Supplier is defined in the following way: A business partner who offers or provides materials or services. Sign, intension and extension are in concordance - the term is clearly and uniquely defined. Page 24 of 113

25 Synonyms In the case of synonyms, the same object or the same phenomenon is designated by different terms. Figure 7: Synonyms Definition: - Different sign - Same intension - Same extension Example: Telecopier, fax machine Action: If possible, do not use different signs, otherwise reference by means of "alias" Homonyms In the case of homonyms, different phenomena are designated by the same term. Figure 8: Homonyms Page 25 of 113

26 Definition: Example: Action: - Same sign - Different intension - Different extension Order: customer order, vendor order Table: numerical table, kitchen table The signs must be assigned in such a manner that they can be differentiated Equipollence A phenomenon occurs in different roles and is given different names. Figure 9: Equipollence Definition: Example: Action: - Different sign - Different intension - Same extension Vendor, customer The different intension must be made clear using different features. Page 26 of 113

27 Vagueness Different names suggest the same meaning of a phenomenon. Figure 10: Vagueness Definition: Example: Action: - Different signs, however suggesting the same intension - Vague intension - Unclear extension Branch, branch office The meaning of the terms must be clarified on the basis of their features. The range of meaning must be clarified. Page 27 of 113

28 Imprecise Usage Figure 11: Imprecise Usage Definition: Example: Action: - Sign that suggests a differing intension - Same intension - Same extension working storage Core memory (meaning main memory) Originally the term described another object, but it continues to be used as a matter of tradition. A suitable term must be found. Page 28 of 113

29 In the table below, all the defects presented above are shown in summarized form. Sign Intension Extension Synonym = = Homonym = Equipollence = Vagueness = not clear Imprecise Usage = suggests = Table 1: Linguistic Defects It is important to avoid linguistic defects when establishing terms: They have to be clarified! Reconstructing Terms Establishing Terms To find a term the following sequence applies: Semantics Definition Term 1. Get an understanding of the object. Describe the business semantics. 2. Write a definition according to the business understanding 3. Find the term according to the definition o o Use the commonly used business term, if exists Otherwise, determine the term by putting together the main terms that make up the semantics For objects with common features, a term is searched for or confirmed as correct. Page 29 of 113

30 Terms are differentiated according to whether they are classifying terms or characterizing terms. A classifying term groups together objects of the real world whose main features are identical. An entity type is established for it. Figure 12: Establishing Terms: Classification A characterizing term describes a characteristic or a feature of an object of the real world. An attribute is established for it. Example: last name, first name, birthday Figure 13: Establishing terms: characterization Page 30 of 113

31 Linkage of Terms Figure 14: Creating terms: linkage of terms For ranges of meaning that result from the combination of sub terms to form a complex whole, a term is searched for or confirmed as correct. Example: Marriage Plant material = relationship between man and woman = relationship between plant and material Aggregation of Terms Figure 15: Aggregation of Terms For a uniform whole that is composed of identical or different objects, a term is searched for or confirmed as correct. Example: Car = motor + tires + body + steering wheel +... Machine group = machine 1 + machine 2 + Page 31 of 113

32 Generalization of Terms Figure 16: Generalization of Terms For classifying terms, a generic term is searched for or confirmed as correct. The reconstruction is initiated by the possible inclusion of one or several terms in another term. Example: Vehicle = car, truck,... Means of transport = airplane, bus, car, ship, bicycle, Eliminating Linguistic Defects Entity types are representations of sets of similar objects (sets of similar entities) of the real world. They are named by a term. To name an entity type properly, a special importance is attached to establishing the term and eliminating linguistic defects (homonyms, synonyms, and so on). In object modelling the name of an entity type is of high importance. The term has to be established properly without any linguistic defects, that is, synonyms, homonyms etc. Page 32 of 113

33 3.3 Pattern A pattern is an abstraction that describes the structure of a problem solution for a subject matter by specifying its essential elements. The pattern represents reusable know-how that can be applied to analogous subject matters. Patterns therefore ensure that similar facts are uniquely described and, by this, simplify the complexity of the whole system. The use of Patterns in description thus supports analysis, structuring and comprehension. Patterns are classified into the following categories Terminological Patterns - Used for the definition of terms Structure Patterns - Used for structural interrelations Business Patterns - Used for business-related facts Page 33 of 113

34 3.3.1 Terminological Patterns Similar semantic concepts are shown explicitly. This is achieved by attaching a standardized prefix or suffix to the name of entities that represent a similar set of facts, and by providing the definitions of such sets of facts with the same structure Grouping Together and Dividing Up Figure 17 shows some selected partial aspects for which standardized names have been agreed. The terms class, type, group, category, kind and grouping are classified according to their nature and on the basis of the criteria assigned to them. Figure 17: Terminological Patterns Class, type and group have a "grouping-together" and, as a rule, "generative" effect on their dependent entity types, whereas category, kind and grouping "divide up" and "reference" their dependent entity types but do not "generate" them. Page 34 of 113

35 Grouping together / determination of the nature of entities by a type or a group The terms group, type and class are used to describe the grouping together (not the dividing up!) of entities, or their essential nature. To define the terms, the following model definitions are used: Class: A class is a grouping together (classification) of any entities that have the same features. The grouping together is independent of the object or the intended purpose and thus objectively related to attributes of the entities. Model definition: A... class is a grouping together (classification) of... (entities) according to... (essential criteria). Example of definition: A work center class is a grouping together (classification) of work centers according to accounting requirements. Type: A type characterizes the essential nature or totality of an entity (in contrast to the kind, this essential nature cannot be defined in terms of individual features). An entity is assigned to a type (a kind divides up entities according to certain criteria). Since a type represents the abstracted (ideal) idea of an entity, a transition to a higher abstraction level (meta-level) is always connected with this idea. Model definition: A... type describes the essential nature of... (entity types), according to... (characteristics of this essential nature). Example of a definition: A work center type describes the essential nature of work centers according to their characteristic equipment. Example: assembly line work center. Page 35 of 113

36 Group: A group is the grouping together (classification) of entities according to a subjective viewpoint, that is, a group designates a set of entities that are grouped together on the basis of a subjective criterion. Model definition: A... group is a grouping together (classification) of... (entities) according to... (viewpoints). Example of a definition: A work center group is a grouping together (classification) of work centers according to their spatial arrangement. Example: Work centers in sales and distribution. Dividing up of entity types by category, kind or grouping: Category and grouping always describe the dividing up (classification) of entities according to certain criteria. A kind is understood to describe the dividing up (classification) of entities on the basis of certain nature-determining features. The crucial point is that the terms category, kind and grouping only designate a grid by which entities are divided up. They do not designate the set of entities resulting from the division. For example, the entity type customer grouping designates a dividing up (classification) of customers according to different viewpoints and does not designate the set of customers resulting from the division. To define the terms, the following model definitions are used: Category: A category is a dividing up (classification) of entities according to objective criteria. Model definition: A... category is a dividing up (classification) of... (entities) according to... (objective criteria). Example of a definition: A work center category is a dividing up (classification) of work centers according to statutory safety regulations. Example: Work centers protected against radiation. Page 36 of 113

37 Kind: A kind is a dividing up (classification) of entities according to characteristic, not necessarily objective criteria. It it thus used to divide up entities according to certain viewpoints. Model definition: A... kind is a dividing up (classification) of... (entities) according to... (criteria = several identical characteristics). Example of a definition: A kind of work center is a dividing up (classification) of work centers according to the level of training required for the person occupying the work center. For example: system developer. Grouping: A grouping is a dividing up of entities according to subjective criteria. The criteria are subjective in the sense that, with the criterion for the division, reference is made to features that do not need to be attributes of the entity. A... grouping is a dividing up (classification) of... (entities) according to... (subjective criteria). Example of a definition: A work center grouping is a dividing up (classification) of work centers according to the risk of accident associated with them. Example: hazardous work centers. Page 37 of 113

38 Version and Variant Version and variant are used as further standard constructs to describe the time-dependent or parallel use of entities of an entity type. To define entity types as variants and versions, the following model definition is used Version A version is a differentiation of entities of an entity type at different points in time. As an extension of this, the differentiation of entities of an entity type at different points in time is also named a version when instances of entity types differ not only with regard to their features but also with regard to feature assignments of secondary importance. Model definition: A... version is a (dividing up)... (entity) that can occur in several different instances at different points in time. Example of a definition: An accounting transaction figure version is a dividing up (classification) of accounting transaction figures on the basis of common assumptions, common reporting purposes, or a common level of knowledge, that makes it possible for an accounting transaction figure to adopt different values at different points in time Variant The term variant designates the differentiation of entities of an entity type at a point in time. As an extension of this, the differentiation of entities of an entity type is also named a variant when instances of entity types differ not only with regard to their features but also with regard to feature assignments of secondary importance. Model definition: A... variant is a (dividing up)... (entity) that can occur in several different instances at the same point in time. Example of a definition: A currency exchange rate type variant is a dividing up of currency exchange rate type - consolidation according to certain criteria, such that this can occur in several different instances at the same point in time. Page 38 of 113

39 Catalogue A catalog is a list of entities that is systematically arranged. The crucial point is that the catalog describes an association of general validity in a very large context. Model definition: A... catalog is a systematically arranged list of... (entities). Example of a definition: A bank catalog is a country-specific, systematically arranged list of banks. Page 39 of 113

40 3.3.2 Structure Patterns Sets of facts that are structurally identical are represented by Structure Patterns. A Structure Pattern has an established internal structure that reproduces the interrelationships between the entity types and the relationship types involved. In the following such structural patterns are described Hierarchy and Net Relationship Entities of an entity type can be arranged in a hierarchy or net by means of directed (ancestorsuccessor) relationships. The position of an entity relative to a focus entity is expressed using a standardized term as name prefix. These standardized terms are shown in Figure 18. However, if an established term exists for the special business meaning this is to be used instead. Top Super ordinate Focus Entity Parent Sub ordinate Child Leaf Figure 18: Standardized Terms Expressing the Position of an Entity within a Hierarchy or Net Meaning of standardized prefix: Parent: Child: Superordinate: Subordinate: Top: Leaf: Direct ancestor of focus entity Direct successor of focus entity Direct or indirect ancestor of focus entity Direct or indirect successor of focus entity Direct or indirect ancestor of focus entity that has no parent Direct or indirect successor of focus entity that has no child Page 40 of 113

41 Use: These terms are used for naming of elements, relationships, actions and queries. Examples: Element: ParentCommunicationArrangementUUID Element of root node of BO Communication Arrangement that specifies the UUID of its directly superordinate arrangement Association: Top Organizational Centre Association to the top organizational centre within a hierarchy of organizational centres Item An item describes features of an entity type that can be grouped together to form their own entity type because a common meaning of their own underlies them (for example, the entity type purchase order with the features for the individual purchase order items that are grouped together in an entity type purchase order item). Between an entity type and its item there is always a hierarchical or quasi-hierarchical relationship. The cardinality of the relationship can be 1 : n as well as 1 : cn. In the case of the entity type chart of accounts, there is a hierarchical relationship of the cardinality 1 : n with the entity type chart of accounts item, since a chart of accounts has at least one item in all cases. By way of contrast, between the entity types order - sales and order - sales - item there is a hierarchical relationship of the cardinality 1 : cn, since at first an order can only consist of an order header without items. Items can be defined on the basis of the superordinate entity type. However, the definition of the superordinate entity type must be comprehensible without the definition of its item. The item is existentially dependent upon its superordinate entity type and not the reverse. Example of a definition: A chart of accounts item is a category of values or value flows that can be recorded or represented in amounts of money in accounting. A chart of accounts is a superordinate list of categories of values or value flows that is defined in accounting... Page 41 of 113

42 Assignment Assignment is the most general standardized term. It describes the aggregation of several different entity types. The name assignment is only used when this relationship structure cannot be described more exactly or if it cannot be assigned to any other standardized structure. Figure 19: Structure Pattern: Venn Diagram of an Assignment Assignments can only be differentiated through the kind (cardinality) of relationships by which they are formed. For the definition and the use of the term assignment, it is specified that the second entity type is assigned to the first. Figure 20: Structure Pattern: Assignment Example of a definition: An item of equipment - bill of material assembly - assignment assigns to an item of equipment, by means of a bill of material assembly, a bill of material that describes its composition. The definition of the assignment relationship must also clearly state which entity type is assigned to which other entity type. Where relationships between entity types are of the assignment relationship type, reference is made in the description of the relationship type to the entity type participating in the assignment Page 42 of 113

43 Determination The standardized term determination is used when, by means of the aggregating relationships between several entity types, an entity is "found". Between this entity type and the aggregated entity type (with the term determination) there is a referential relationship. A determination is formed through the aggregation of several entity types. It references the entity type to be found. A distinction is made between entity types that semantically characterize the determination and entity types that differentiate it. Taking the entity type business area determination as an example, a business area is found through the aggregation of plant and division. The plant semantically characterizes the determination whereas the division is used for differentiation. Figure 21: Structure Pattern: Determination Example of a definition: A business area determination assigns a business area to a plant in dependence upon the division. Page 43 of 113

44 3.3.3 Business Patterns A business pattern is a structure pattern whose use can be extended to analogous business-related facts and their relationships. As a result, structural analogies become apparent. These help the user to gain a deeper understanding of complex facts and their interrelationships Business Transaction Documents A business transaction document (BTD) is a document which represents a business transaction. It is defined with respect to a specific point in time. Comment: A business transaction is a self-contained, logically connected, commercial transaction that results in a value change and/or quantity change. The basic structure of a BTD follows a pattern (see Figure 21). With each level a certain understanding is associated. Who : Involved party What : Subject of the business transaction When / How much : Consideration of quantity and time Object Root BTD Item Sched. Line Who What When / How much Figure 22: Basic Structure of Business Transaction Document Page 44 of 113

45 This basic structure of a BTD is reflected in the following five categories. They are used as building blocks for the definition of a BTD: Activity / Character: The definition always starts with a term specifying the activity or character of the represented business transaction such as request and confirmation. Involved Parties (Who): This is followed by the parties involved in the business transaction such as customer and seller. Subject Matter (What): The third part contains the subject of the business transaction such as delivery of products and paying of invoices. Time / Quantity (When / How much) This is followed by the specification of the schedule line and quantities for the subject of the business transaction. Additional Information The last part contains additional information about the object that is of technical nature and needed for its understanding The building of a BTD definition according to these categories is shown in Figure 23. Activity / Character Who What When / How much Additional Info A(n) <BTD> is a requirement a requisition a request an order a confirmation an organization a buyer a creditor at certain points in time within a period of time regularly a specified quantity procurement of goods and services deliver materials perform a specified service remunerations to be paid collect a debt Additionally it contains the results of the resolution, as well as the expenses incurred. Figure 23: Definition Pattern for Business Transaction Document Page 45 of 113

46 Figure 24 shows standardized terms for the Activity / Character used for the definition of a BTD. Activity / Character Requirement Semantics A statement that expresses a demand required in advance. Usually a requirement is derived from a forecast is Requisition Request An inquiry to a party to fulfil a demand. Usually this inquiry is company internal and triggers the creation of an order An inquiry with obligation to a party to do something. That can be the execution of an activity which involves the change of a state or subject matter. A request incorporates an obligation. Order A stated intention to engage in a business transaction for specific products. Confirmation An assurance with obligation about the fulfilment of a request. Figure 24: Standardized Terms Used for Activity / Character Examples: Purchase Order A request from a buyer to a seller to deliver a specified quantity of material, or perform a specified service, at a specified price within a specified time. Internal Request A request from an employee of a company for the procurement of goods or services for own or company use. Service Request A request from a customer to a service provider to solve an issue that the customer has with regard to a product. In addition to the description and the categorization of the issue, the Service Request contains the documentation and the results of the resolution, as well as the expenses incurred. Page 46 of 113

47 Semantics 2 Abstraction Scoping & Understanding 3 Definition 1 Topic 4 Term enterprise SOA Object & Service Operation Design 4 Naming Rules for Model Entities 4.1 Naming Rule Notation A naming rule specifies how the name of an entity is composed from individual terms. The composition is defined by an expression using the following notation. x - x is fixed term (terminal) <x> - x is variable term according to a specified rule (nonterminal) * (star) - The previous item occurs zero, one or many times + (plus) - The previous item occurs one or many times? (question mark) - The previous item is optional (occurs zero or one times) (pipe) - Either the previous or the successive item occurs (expression) - Round brackets group the expression between them A naming rule is given by an expression for the name and the definition of the individual terms within the expression. If possible specify natural-language rules and controlled vocabulary for the individual terms. Provide an example that covers the full complexity of the syntax. Example for the naming rule for Node Data Types: The name of a node data type is composed of the business object name, followed (if the node is not the root node) by the node name, followed by the fixed term Elements. Naming Rule Building Syntax: <object><node>?elements <object>: <node>: Name of object; in case of template without _Template Name of node; omitted in case of root node Example: Name of NDT for node Item within BO Customer Invoice is CustomerInvoiceItemElements. Page 47 of 113

48 4.2 Semantic Name and Technical Name The naming rules describe how to build the semantic name of an object in conceptional modeling. Therefore no length restrictions arise. However, depending on the technical representation in the modeling tool or implementation environment length restrictions may occur. For detailed rules concerning abbreviation refer to chapter 5, page 95. In addition to the naming rules the style of capitalization has to be decided. Conceptional Modeling (no tool restrictions) Technical Representation (ESR) BO Node - Elements Semantic Name Title Case Technical Name UpperCamelCase Figure 25: Capitalization of Semantic Name and Technical Name Semantic names of model entities are in Title Case. Technical Names of model entities are in UpperCamelCase. Note: The semantic name of a Data Type, Element, Code and Code List is in UpperCamelCase. The semantic and technical name of an Attribute is in lowercamelcase. Title Case: Words of a name are separated by spaces. The first letter of each word is capitalized, except the following Coordinating conjunctions (and, but, for, nor, or) Prepositions of four or fewer letters (at, for, per, to, with) Articles (a, an, the, some) unless the article is the first or last word in the title The word to in an infinitive phrase Detailed Title Case Rules Upper Camel Case: Words of a name are capitalized and there are no spaces between them. Lower Camel Case: Same as Upper Camel Case with the first letter in lower case. Page 48 of 113

49 4.3 Object Syntax: <qualifier>*<object>? <qualifier>: <object>: Term describing a subtype or view of the <object> Term for self-contained real world (business) concept If the <qualifier> is a unique term of its own and already contains the meaning of <object> the <object> is omitted. Examples: Payment Register (qualifier: Payment, object term: Register) Customer Business Partner (qualifier Customer is unique term of its own, therefore term Business Partner is omitted) Object Template Syntax: <generalized term>_template <generalized term>: Term expressing common semantics of projected objects Examples: Business Partner _Template Procurement Document _Template Page 49 of 113

50 4.4 Object Node Syntax: <path>?<qualifier>*<main node semantics>? <path>: Hierarchical path with first level omitted <qualifier>: Term expressing the semantic restriction of the <main node semantics> <main node semantics>: Term expressing the main semantics of the node in the context of the path If the <qualifier> is a unique term of its own and already contains the meaning of <main node semantics>, the <main node semantics> is omitted. The name of root node is identical to the object name. Exceptions: See section and Examples: Party (party in BO below root node) Item Schedule Line (schedule line in BO below node Item) Purchase Order (root node of BO Purchase Order) Address_Template (root node of template object Address_Template) Specialization Node Case: Specialization of node not taken over from aggregating node: Syntax: <qualifier>+<generalization node>? <qualifier>: <generalization node>: Term expressing the specialization of the <generalization node> Name of generalization node, omitted if <qualifier> is unique term of its own Example: Node Item Party is specialized according to the role Buyer Party. The name of the specialization node is Buyer Item Party (not Item Buyer Party ) Page 50 of 113

51 Case: Specialization taken over from aggregating node Syntax: <path><qualifier>+<generalization node without path>? <path>: Hierarchical path that is part of the generalization node name with first level omitted <qualifier>: Term expressing the specialization of the generalization node <generalization node without path>: Name of node that is generalization omitting the path If the <qualifier> is a unique term of its own, <generalization node> is omitted Example: Node Item Business Transaction Document Reference is specialized according to the referenced object Purchase Order. The name of the specialization is Item Purchase Order Reference. Page 51 of 113

52 4.4.2 Grouped Object Node Syntax: <path without parent node><grouped object> <path without parent node>: <grouped object>: Hierarchical path with both first level and parent node of grouped object omitted Name of the grouped object represented by the node Examples: Grouping Object at root node level: Product Categories are grouped by an Product Category Hierarchy. The name PCH is not part of the name of the node representing the Product Category. As the root node is never repeated in nodes below root node this has only a consequence in the naming of relationships from Product Category to nodes of another object. Grouping Object Product Category Hierarchy Product Category Hierarchy Product Category Grouped Object Figure 26: Example for Grouping Object at Root Node Level Grouping Object at non-root node level: Objects X are grouped by node X Group below Item node. The name X Group is not part of the name of the node representing the object X. Therefore the node is named Item X (and not Item X Group X ). Grouping Object Header Item Item X Group Item X Grouped Object Figure 27: Example for Grouping Object at Non-Root Node Level Dependent Object Inclusion Node Syntax: <path><qualifier>*<do> Page 52 of 113

53 <path>: <qualifier>: <DO>: Hierarchical path with first level omitted Term expressing a special role of the DO within its host object Name of dependent object Example: Hosting object Sales Order, node Item contains the DO Attachment Folder in the role Receipt. Corresponding name of DO inclusion node: Item Receipt Attachment Folder Transformation Node The naming of a transformation node follows the common naming rules for object nodes. Page 53 of 113

54 4.5 Relationship Syntax for Basic Pattern: source node target node <qualifier>*<object>?<node>?<object>?<node>? <qualifier>: <object>: <node>: Term expressing the meaning of the relationship or the role of the source/target node for the relationship; needed to distinguish several relationships with same source and target node Name of source/target object Name of source/target node <object> and <node> can be replaced by its subtypes. For a relationship name, the given context is omitted from the basic pattern. Figure 28 shows which naming parts are omitted for each relationship type. Relationship NR Decision Tree source target <q><bo><node><bo><node> Inbound (Ass, Aggr) Direction? Outbound (Comp, Nav Ass) source target <q><bo><node><bo><node> source target <q><bo><node><bo><node> Intra BO? Intra BO? No Yes No Yes source source target target <q><bo><node> <q><bo><node> <q><bo><node> <q><bo><node> Figure 28: Naming Rule Decision Tree If a naming conflict (homonym) occurs, do not omit <BO> in intra-bo relationship name. Page 54 of 113

55 The following table shows for each relationship type which naming parts may occur in the relationship name (indicated by + ) and which parts do not occur (indicated by - ). Qualifier Source Target <object> <Node> <object> <Node> Inbound Outbound Aggregation / Association (intra object) Aggregation / Association (inter object) Composition (intra object only) Association for Navigation (intra object) Association for Navigation (inter object) + +* * Table 2: Summary of Relationship Name Syntax * Omitted if no naming conflict occurs Naming Conflict BTD BTD Item Item Location Location Location Location <q>location <q>btdlocation Do not omit <BO> from relationship name Figure 29: Naming Conflict and Resolution Naming conflicts are situations where two different relationships have, according to the naming rules, the same name (homonyms). They may occur when a node has the same name as another (existing or upcoming) BO. In that case it is not possible to determine the source (inbound) or target (outbound) node from the relationship name. Resolution of naming conflict To resolve a naming conflict the BO-context is not omitted in the relationship name. Page 55 of 113

56 Naming examples for different cases are shown in the following picture. Focus: Node A B BC BG BCD BG BCD A E F E X F BCH BCH VW X X Y XY V V W Legend: Structural relationships Association for Navigation Figure 30: Naming examples for different relationship types The naming rules for the individual relationship types are explained in the following sections. For self reflexive relationships see section 4.5.5, Structure Relationships Composition Syntax: <target node> <target node>: Name of target node of the composition Example: Name of composition from node Item to node Item Schedule Line is Item Schedule Line. Note: The naming rule for filtered compositions is identical Aggregation / Association Syntax: <qualifier>*<source object>?<source node>? <qualifier>: <source object>: <source node>: Term expressing the meaning of the relationship or the role of the source node for the relationship; needed to distinguish several relationships with same source and target node Name of source object, omitted in case of intra-bo relationship and if no naming conflict with an inter-bo relationship occurs in current or future scope Name of source node; omitted for inter-bo relationship in case of root node Example: Name of Inbound association from root node of BO Identity with role creation is Creation Identity. Page 56 of 113

57 4.5.3 Association for Navigation Syntax: <qualifier>*<target object>?<target node>? <qualifier>: <target object>: <target node>: Term expressing the meaning of the relationship or the role of the target node for the relationship; needed to distinguish several relationships with same source and target node Name of target object, omitted in case of intra-bo relationship and if no naming conflict with an inter-bo relationship occurs in current or future scope Name of target node, omitted for inter-bo relationship in case of root node Example: Name of Association for Navigation from root node of DO Address to node Telephone (intra BO) with role default is Default Telephone Name of Association for Navigation from node Execution of MDRO Production Order Release Run to root node of BO Application Log is Application Log Filtered Association for Navigation Syntax: <qualifier>+<target object>?<target node>? <qualifier>: <target object>: <target node>: Name expressing the filter semantics Name of target object, omitted in case of intra-bo relationship and if no naming conflict with an inter-bo relationship occurs in current or future scope Name of target node, omitted for inter-bo relationship in case of root node Example: Filtered association for navigation from root node of business partner to node Role with filter based on role category. Name of association for navigation: Role Category Based Role Note: The naming rule for filtered compositions is identical to the naming rule for compositions. Page 57 of 113

58 4.5.5 Structure Relationships Hierarchy Relationship Without Attributes to <node> from Syntax for inbound association relationship: <qualifier><node> <qualifier>: <node>: Fixed term Parent or term expressing the meaning of the parent node instance Name of node Example: Items of a Sales Order may be arranged hierarchically. The name of the inbound association relationship is Parent Item Hierarchy Relationship With Attributes <node> <Node> <Hierarchy Relationship> Syntax for relationship node: <node><hierarchy relationship> <node>: <hierarchy relationship>: Name of node Fixed term Hierarchy Relationship or term expressing the meaning of the hierarchy relationship The name of the composition relationship is the same as for the relationship node. Page 58 of 113

59 Syntax for inbound aggregation relationship: <qualifier><node> <qualifier>: <node>: Fixed term Parent or term expressing the meaning of the parent node instance Name of node Example: Items of an Inbound Delivery may be arranged hierarchically; the relationship contains attributes. Name of relationship node: Item Hierarchy Relationship Name of composition relationship: Item Hierarchy Relationship Name of inbound aggregation relationship: Parent Item Page 59 of 113

60 Net Relationship With or Without Attributes <Node> <Node> <Net Relationship> Syntax for relationship node: <node><net relationship> <node>: <net relationship>: Name of node Fixed term Net Relationship or term expressing the meaning of the net relationship The name of the composition relationship is the same as for the relationship node. Syntax for inbound aggregation relationship: <qualifier><node> <qualifier>: <node>: Fixed term Parent or more specific term expressing the meaning of the parent node instance Name of node Page 60 of 113

61 Cross References within Same Level <Node> Syntax for inbound association relationship: <qualifier><node> <qualifier>: <node>: Term expressing the role of the related node instance, such as Predecessor, Successor Name of node Example: Predecessor / Successor Relationship between Operation Activities Operation Operation Activity Bill of Operations Operation Operation Activity The name of the inbound association relationship is Predecessor Operation Activity. Page 61 of 113

62 4.6 Data Type Node Data Type Syntax: <object><node>?elements <object>: <node>: Name of object the node belongs to; in case of template without _Template Name of node; omitted in case of root node Example: The name of NDT for node Item within BO Customer Invoice is CustomerInvoiceItemElements Intermediate Data Type Syntax: <object><node>?<element> <object>: <node>: <element>: Name of object; in case of template omit _Template ; omitted in case of allowed reuse Name of node; omitted in case of root node or in case of allowed reuse Name of the grouping element that is to be typed by this IDT Example: Element Status groups all status elements of a Customer Invoice Item The name of the IDT is CustomerInvoiceItemStatus Page 62 of 113

63 4.6.3 Filter Data Type Syntax: <filter>filterelements <filter>: Name of filter. Two cases are distinguished: FDT is reusable across several relationships: <filter> expresses the filter semantics, that is, the elements that belong to the FDT FDT is relationship specific: <filter> is built according to the following syntax: <source object>?<source node>?<relationship> <source object>: <source node>: <relationship>: Name of object the source node belongs to Name of source node of filtered relationship, omitted in case of root node or in case the <relationship> is a composition Name of filtered relationship (composition, association for navigation) Examples: Filter at composition (from BO Compensation structure root node to node Grade ): CompensationsStructureGradeFilterElements (no reuse) Filter at association for navigation (from BO Business Partner root node to BO Position root node) BusinessPartnerPositionFilterElements (no reuse) Filter not relationship specific: ValidityPeriodFilterElements (reuse) Page 63 of 113

64 4.6.4 Key Data Type Syntax: <object><node>?<key qualifier>?key <object>: <node>: <key qualifier>: Name of object for which the KDT is defined Name of object node for which the KDT is defined, omitted in case of root Semantically qualifier required to differentiate from other keys (according to semantics); not needed for main key of node Examples: KDTs for keys of node Sourcing List Item within BO Sourcing List KDT for main key: SourcingListItemKey KDT for key consisting of ID elements: SourcingListItemIDKey Definition Pattern for KDT A grouping of elements that uniquely identifies <object><node>? according to <grouping criteria> <object>: <node>: <grouping criteria>: Name of object for which the KDT is defined Name of object node for which the KDT is defined, omitted in case of root Criteria from a business point of view what elements are grouped to identify uniquely an object, object node Page 64 of 113

65 4.6.5 IDT replacing a GDT Including Keys instead of IDs For an aggregated GDT that includes IDs it might be necessary to create a data type that is identical to the GDT but uses the corresponding keys instead of the ID. For this an IDT is created following the following naming rule. Syntax: ObjectNode<name of aggregated GDT> <name of aggregated GDT>: Name of the aggregated GDT where the ID is replaced by a key Example: Element PartyID within GDT LocationAddressReference needs to be replaced by PartyKey. The name of the corresponding IDT is ObjectNodeLocationAddressReference. Comment: When using the IDT for typing an object node element the fixed term ObjectNode is replaced by the name of this node. For the element name the object node is truncated. As a consequence the element name is not influenced by the fixed term ObjectNode (after truncation <name of aggregated GDT> remains) Action Data Type Syntax: <object>?<node>?<action>actionelements <object>: <node>: Name of the object the action belongs to, omitted if reused across several objects Name of the node the action belongs to, omitted in case of root node or if reused across several nodes <action>: Name of the action Examples: Without reuse: Name of ADT for action Notify of Invoice Cancellation on node Customer Invoice Request Item is CustomerInvoiceRequestItemNotifyOfInvoiceCancellationActionElements With reuse across several objects: Name of ADT for action Check Archivability is CheckArchivabilityActionElements Page 65 of 113

66 4.6.7 Query Data Type Syntax: <object>?<node>?<selection criteria view>queryelements In case of content view the following syntax applies: <object>?<node>?<response view>by<selection criteria view>queryelements <object>: <node>: Name of the object the query belongs to, omitted if reused across several objects Name of the node the query belongs to, omitted in case of root node or if reused across several nodes <response view>: Name of content view <selection criteria view>: Name of selection semantics Semantically name (e.g. Planning Information) Sequence of main selection parameters concatenated by and Elements for maximal set of selection criteria Examples: BusinessPartnerBankDetailsQueryElements Name of QDT for query Query By Bank Details at root node of BO Business Partner CustomerInvoiceCompanyAndDateQueryElements Name of QDT for query Query By Company and Date at root node of BO Customer Invoice EmployeeTimeAgreementItemElementsQueryElements Name of QDT for query Query By Elements at item node of BO Employee Time Agreement LocationTopLocationByIDQueryElements Name of QDT for query Query Top Location By ID with content view Top Location Query Intermediate Data Type Syntax: QueryElement<object>?<node>?<grouping element> QueryElement: Unique prefix, omitted from element name <object>: Name of object the query belongs tot; omitted if reused across several objects <node>: Name of node the query belongs to; omitted if reused across several nodes <grouping element>: Name of the semantic subject represented by the grouped elements. The name is the same as the corresponding element in the object model or solely within the query Page 66 of 113

67 Remarks: It depends on the reuse scope whether Query IDT name contains <object> or <node>: Specific for single node (no reuse) full name Reuse within object, across nodes <node> not part of name Reuse across objects <object>, <node> not part of name Rationale for omitting prefix QueryElement : Only an element in a query is typed by a Query IDT. Thus, the common shortening rule applies Naming Rule for element in core query: <object> is always omitted from element name <node> is omitted from element name, if query resides at this node (common rule) Example: Queries of business object Bank Directory Entry have a solely defined grouping element AddressOrganisationName. The name of the Query IDT is: QueryElementBankDirectoryEntryAddressOrganisationName Page 67 of 113

68 4.6.9 Extension Data Type The following rules are valid only for NDTs, QDTs and IDTs within a MDT. BO MT A 1 0..* B A B Extension 0..* C Extension C Figure 31: Extension of a node data type and its corresponding message intermediate data type Syntax for DTs of form <X>Elements (with suffix Elements ): <X><extension view name>extensionelements <X>Elements: <extension view name>: Name of a data type that is to be extended such as Node DT, Query DT Name expressing the meaning of the extension; for country specific extensions <country code>_ Examples Country specific extension of Node DT EmploymentElements Name of extension DT: EmploymentDE_ExtensionElements Country specific extension of QDT BusinessPartnerIdentificationAndAddressQueryElements Name of extension DT is BusinessPartnerIdentificationAndAddressQueryUS_ExtensionElements Page 68 of 113

69 Syntax for DTs of form <X> (without suffix Elements ): <X><extension view name>extension <X>: Name of a data type that is to be extended such as Intermediate DT <extension view name>: Name expressing the meaning of the extension; for country specific extensions <country code>_ Example Procurement specific extension of message data type IDT SourcingListItem Name of extension DT: SourcingListItemProcurementExtension Page 69 of 113

70 4.7 Data Type Element Syntax: <qualifier>*<element term> <qualifier>: <element term>: Term expressing semantic restrictions of the element Term expressing the meaning of the element in the context of the data type The element must be unique within its aggregated data type (such as Node DT, Action DT, Query DT, Filter DT) Usually the element name must contain the name of the data type by which it is typed. For detailed rules regarding shortening and replacement of parts of the data type name within the element name see naming rules for elements of aggregated data types in the GDT guideline. Examples: Element NetAmount Qualifier: Net; element term: Amount; typed by GDT Amount Element ID Element in the NDT of root node of BO Supplier Invoice Note: The element is typed by GDT BusinessTransactionDocumentID. For the element name the term BusinessTransactionDocument is omitted because Supplier Invoice is a Business Transaction Document (replacement rule) and the element is located at the root node of the BO Supplier Invoice (shortening). Page 70 of 113

71 4.7.1 Elements of a Node Data Type Syntax: <qualifier>*<element term> <qualifier>: <element term>: Term expressing semantic restrictions of the element Term expressing the meaning of the element in the context of the object node The element must be unique within its NDT. The node data type name and the element name have to be regarded as semantic unit Redundant and semantically identical parts of element name and node data type name have to be removed in the element name (truncation rule) Elements as a suffix is ignored for truncation rule. For detailed rules regarding shortening and replacement of parts of the data type name within the element name see naming rules for elements of aggregated data types in the GDT guideline. Note: Element naming of NDTs for Transformation Nodes follows the same rules as for normal nodes. The origin of the information must either be determinable by the element name or by its documentation. In case, that the element of the NDT is calculated, this calculation must be described in the element documentation. Example: The node data type SupplierInvoiceItemElements contains the following elements: ID typed by GDT BusinessTransactionDocumentItemID TotalReleasedQuantity typed by GDT Quanitiy and with first level qualifier Released Aggregated Status Element Syntax: <node>list<status element> <node>: Name of the subordinate node containing the status that is to be aggregated <status element>: Name of the status element that is aggregated Example: Node Customer Invoice Request Item contains the element CancellationStatusCode. The aggregated status on root node of Customer Invoice Request has the element name ItemListCancellationStatus- Code. Page 71 of 113

72 4.7.3 Element Typed by Key The name of a key element depends on whether the key element is located at the node identified by the key (own key) or whether it is located at a referencing node (foreign key). Element name in (defining) object node Syntax: <key qualifier>?key <key qualifier>: Term expressing the differentiation of the key from other keys identifying the same node; not needed for main key of node Note: Pay attention that for the defining node the KDT naming parts <object> and <object node> are not part of the name of the element typed by the KDT. Examples: Keys of node Sourcing List Item within BO Sourcing List Element name for main key: Key Element name for key consisting of ID elements: IDKey Definition Pattern for Element name in defining object node Same as Definition Pattern for KDT (see 4.6.4, page 64). Page 72 of 113

73 Element name in other (referencing) object node Syntax: <qualifier>*<key data type> <qualifier>: Role of relationship; same as corresponding relationship < key data type >: Name of key data type of the referenced object node Common shortening rule for name of key element in node applies. Examples: Inbound association from node Item of BO Sourcing List Name of corresponding element is SourcingListItemKey (typed by KDT SourcingListItemKey) Inbound association from root node of BO House Bank Account with the semantic Destinated : Name of corresponding element is DestinatedHouseBankAccountKey (typed by KDT HouseBankAccountKey, Qualifier: Destinated) Elements of a Key Data Type Note that in distinction to an element typed by a KDT the elements here are part of the KDT. Syntax: <object><node>?<element> <object>: <node>: <element>: Name of the object the corresponding element belongs to Name of the node the corresponding element belongs to; omitted in case of root node Name of element that is used within the KDT to identify the node KDT elements contain the complete hierarchical path of the used elements. Page 73 of 113

74 Example: Hugo ID (GDT: HugoID) Item ID (GDT: HugoItemID) Key (KDT: HugoItemKey) - HugoID (GDT: HugoID) - HugoItemID (GDT: HugoItemID) Figure 32: Example for Key Data Type Elements The identifier of Node Item of object Hugo is unique only in the context of the object. Therefore it is identified by an alternative key composed of HugoID and HugoItemID. Page 74 of 113

75 4.7.5 Action Data Type Element Syntax: <qualifier>*<element term> <qualifier>: <element term>: Term expressing semantic restrictions of the element term Term expressing the meaning of the element for the action Example: Name of ADT Element Quantity that is qualified as Invoiced is InvoicedQuantity. (ADT CustomerInvoiceRequestItemNotifyOfInvoiceCancellationActionElements) Query Data Type Element Syntax: <qualifier>*<element term> <qualifier>: <element term>: Term expressing semantic restrictions of the element term Term expressing the meaning of the element for the query The following rules apply: If the query element corresponds to an element located at the same node as the query, the name is the same If the query element corresponds to an element of a different node, the name reflects its semantics o Chose necessary part of the complete path of the element (The complete path starts at the BO that contains the corresponding element) o Omit duplicates such as AlternativeCurrencyCurrencyCode If the query element is not directly matched to a node element, the name reflects its semantics For typing of an element that groups several elements in the query refer to section 4.6.8, Query Intermediate Data Type. Note: If the meaning of the query element for the query is not trivial, provide a detailed definition. Especially this is the case if the element doesn t correspond to an element located at the same node. Page 75 of 113

76 The next figures provide examples for the naming of elements in compound queries and core queries, respectively, following the aforementioned naming rules. Focus: Object Response View ID, a1 ID, ZID A B BC A BCD BCE BCEF ID, z1 Z Z Y Selection Element Query <ResponseView> By <SelectionCriteriaView> ResponseView Structure: C.. D E F SelectionCriteriaView Structure: a1 Bb1 BCEe1 BCEFf1 Zz1 ZYy1 Figure 33 Compound Query and Response: Element Naming Example Focus: Node Response View: Node ID, a1 ID, ZID A B BC A BCD BCE BCEF ID, z1 Z Z Y Selection Element Query By <SelectionCriteriaView> Response View Structure: C SelectionCriteriaView Structure: Aa1 ABb1 Ee1 ABCEe1 EFf1 ABCEFf1 Zz1 ZYy1 Figure 34 Core Query: Element Naming Example Page 76 of 113

77 4.8 Core Service Operation Action Syntax: <action> <action>: Term expressing the action to be executed Must not be one of the Access-Core-Services (Create, Read, Update, Delete) Examples: Accept, Acknowledge, Activate, Approve, Block, Unblock, Calculate, Cancel, Check, Confirm, Execute, Finish Preparation, Generate Forecast, Migrate, Notify, Release, Replicate, Revoke Obsolescence, Transmit Query Syntax: Query<response view>?by<selection criteria view> <response view>: Only in case of content view <selection criteria view>: Semantically name or main selection parameter Examples: Query By Bank Details (at root node of BO Business Partner) Provides all business partners for the given bank details Query By Company and Date (at root node of BO Customer Invoice) Provides all customer invoices for the given date and company Query By Elements (at item node of BO Employee Time Agreement) Provides all employee time agreements for the given elements Query Top Location By ID (at root node of BO Location with content view Top Location ) Provides for a location the top location in a location hierarchy Page 77 of 113

78 4.9 Compound Service Operation Service View Naming Rules Interface OUT Msg MT OP2 OP1 MT Interface IN e.g. PurchaseOrder e.g. SalesOrder Figure 35: Overview of Naming Rules needed for Compound Service Operations For compound service operations naming rules for interfaces (IF), service operations, message types and message data types are needed Service View The Service View is used in several naming rules and therefore defined centrally in this section. Syntax: <qualifier>*<object>?<component>? <qualifier>: <object>: <component>: Term expressing a semantic restriction of the relevant instances for the service Name of object the service view is derived from Name of sub-structure of the object In case of a subtype (or role) for the object the <qualifier> describes the subtype (or role) of the <object>. If the <qualifier> is an established term and covers the semantics of <object>, then <object> is omitted. Examples: Service View is a Subtype: Location Inventory (with qualifier Location and object Inventory) Customer (qualifier Customer is established subtype name, object Business Partner is omitted) Material (qualifier Material is established subtype name, object Product is omitted) Page 78 of 113

79 Service View is a Role of the Object: Approver (qualifier Approver is established term for the role of object Employee, therefore object Employee is omitted) Service View is a Component: Purchase Order Delivery Terms (with object PO and component Delivery Terms) Employee Delivery Address (with object Employee and component Delivery Address) Service View is a Component of a Subtype: The view of the object Product needed to control service processes for materials is named MaterialServiceProcessControl (object Product is omitted as qualifier Material is an established term and covers the semantics of Product, component is Service Process Control) Page 79 of 113

80 4.9.2 Service Interface Syntax: <interaction activity><direction> <interaction activity>: <direction>: Verb or verb phrase in gerund ( -ing form) or, if not possible, in substantive form Fixed term In or Out A service interface name is unique within a process component. Examples: Request Invoicing Out Fulfillment In Service Operation (Asynchronous) PC1 PC2 <IF>Out <IF>In Op (out) MT MDT Op (In) Syntax (outbound): <transaction activity><service view>?<action>? Syntax (inbound): <action><service view>? or <action><service view>?based on<qualifier>*<object> <transaction activity>: Activity of operation. Allowed terms are Inform of, Notify of, Query, Respond, Request, Confirm <service view>: <action>: <qualifier>: <object>: Service View that defines the operation signature; omitted if the name of the service interface covers the semantics of the service view Verb that states the action that is requested by the operation (in outbound case) is offered by the operation (in inbound case) Semantic restriction of the object on which the action is based Object on which the action is based Page 80 of 113

81 A service operation name is unique within an interface. Operation naming rules apply to all categories of service operations (A2X, A2A, B2B). For operations of reuse service components (RSCs) it is possible that an explicit object is not present. In that case the service view is not based on an object, for example operation Convert Quantitiy. Examples: Notify of Invoice (outbound; with transaction activity Notify of and service view Invoice ) Inform of Purchase Order Cancel (outbound; with transaction activity Inform of, service view Purchase Order and action Cancel ) Maintain Invoice (inbound; with action Maintain and service view Invoice) Create Invoice based on Attachment (inbound; with transaction activity Create, service view Invoice and object Attachment ) Service Operation (Synchronous) Initiating Operation (follows outbound NR) Reacting Operation (follows inbound NR) PC1 PC2 <IF>Out Op (out) MT1 MDT1 MT2 MDT2 <IF>In Op (In) For synchronous operations the following rule applies The name of the o o initiating operation follows the outbound syntax reacting operation follows the inbound syntax. Omit the message type category in the <service view> within the operation name (the <service view> of the incoming and outgoing MT differ by their message type category Request/Confirmation or Query/Response) Page 81 of 113

82 4.9.5 Service Operation (A2X) MT1 MDT1 MT2 MDT2 PC2 <IF>In SV1 PC2 SV2 PC2 Op (In) Reacting Operation (follows inbound NR) For example Manage <BO> For A2X operations the NR for inbound operations (asynchronous or synchronous) applies together with the following additional rule: Omit the BO in the <service view> name within the operation name (the BO name is already contained in the name of the IF the operation belongs to) Note: For A2X only the reacting (inbound) operation is of relevance. The other part can for example be an excel for upload Example: The name of the A2X operation belonging to IF Manage Activity In for mass maintenance of activities is: Maintain Activity Maintain Request Bundle (inbound; with action Maintain, service view Activity Maintain Request and mass processing type Bundle ) The following rules applied Pattern for inbound operations Request omitted (rule for synchronous operations) Maintain omitted (Semantics contained in action name) Activity omitted (rule for A2X operations) Page 82 of 113

83 Semantics 2 Abstraction Scoping & Understanding 3 Definition 1 Topic 4 Term enterprise SOA Object & Service Operation Design Message Type Naming Rule for Message Types Syntax: <service view><action>?<message type category> Building <service view>: Service View contained in the message type, see section <action>: Verb that states the action which the sender of a message expects to be executed on the service view <message type category>: Classification of messages. Valid categories are: Information, Notification, Request, Confirmation, Query, and Response In case the <message type category> (and / or <action>) is reflected in the <service view> (and thus has the same meaning), the corresponding parts of the <service view> name are omitted to obtain the message type name. For synchronous operations and if the restricted message header is used suffix _sync is added to the MT name. For the MDT naming of mass processing messages refer to chapter , page 90. Examples: Purchase Order Cancellation Request with service view PO Cancellation and message type category Request Purchase Order Migrate Request with service view PO Migrate Request, action Migrate and message type category Request Note: It is essential to distinguish between the service view (substantive) providing the structural definition and an action (verb) to be executed on the service view The following examples emphasize the difference between these two aspects: Message type PurchaseOrderCancellationRequest <Service View> request to accept the PurchaseOrderCancellation document contained in the message Cancellation is part of the service view name no action involved Message type PurchaseOrderMigrateRequestMigrateRequest <Service View> <Action> request to migrate the PurchaseOrderMigrateRequest document contained in the message Migrate = action to be executed on PurchaseOrderMigrateRequest Page 83 of 113

84 4.9.7 Message Data Type As a general principle the name of the MDT reflects the MT structure, and thus, is determined by the service view. Syntax: <service view>message <service view>: Service View contained in the MT typed by this MDT, see section For synchronous operations and if the restricted message header is used suffix _sync is added to the MDT name. For the MDT naming of mass processing messages refer to chapter , page 90. Note: Often the MT structure (service view) reflects the MT category and/or action of the MT. Thus the corresponding parts (suffix) of the structure name are omitted to obtain the MT name. In this case the original full name of the MT structure (service view) must be used to obtain the MDT name, because the category-specific (or action-specific) aspect of the MT structure has to be reflected in the MDT name. Example: MT Structure = PurchaseOrderConfirmation MT Category = Confirmation MT structure reflects category resulting MT name is PurchaseOrderConfirmationConfirmation MDT Name is PurchaseOrderConfirmationMessage Examples: (see also example of corresponding message types) PurchaseOrderCancellationMessage with service view PO Cancellation PurchaseOrderMigrateRequestMessage with service view PO Migrate Request Page 84 of 113

85 Message Intermediate Data Type / Element within a Message Data Type MIDT / element name on Business Document Object (BDO) Level: The MIDT name on BDO level is the <service view>. The element name is obtained from the object the MT is derived from. It is the name of the object, the name of a specialization of the object or the name of a service-specific view onto the object. For a compound query there is a special naming rule for the element on BDO level. For this see section , page 89. MIDT / element name below BDO Level For the name of an MIDT below the BDO level two cases appear: - the name of the next higher level MIDT concatenated with the element name of the element to be typed (non-reusable MIDT) - a name chosen according to the generalized semantics of the elements that shall be typed (reusable MIDT) The element name does not contain the name of the next higher level element. Example: MT Purchase Order Cancellation Request is typed by MDT PurchaseOrderCancellationMessage, which is derived from BO Purchase Order. The BDO contains the service view Purchase Order Cancellation. The name of the IDT on BDO level is PurchaseOrderCancellation The name of the element on BDO level is PurchaseOrder The name of the IDT on Item level (directly below BDO) is PurchaseOrderCancellationItem The name of the element on Item level is Item Level 1 Level 2 MT MDT Element IDT Element IDT Purchase Order Cancellation Request Purchase Order Cancellation Message Message Header Business Document Message Header Purchase Order Purchase Order Cancellation Item Purchase Order Cancellation Item BDO Figure 36: Naming of Intermediate Data Types / Elements within a Message Data Type Page 85 of 113

86 4.9.8 Response View The Response View is used in several naming rules for compound Query Response Operations and therefore defined centrally in this section. Query Service Operation Selection Criteria View (operation signature) Response Response View (operation signature) Figure 37: Selection Criteria View and Response View of Compound Query / Response Operations Syntax: <qualifier>*<object>?<component>?simple? <qualifier>: <object>: <component>: Simple: Term expressing a semantic restriction of the object or object component in the response view Object the response view is derived from Component of the object the response view is derived from Fixed term that indicates a simple object response view Page 86 of 113

87 Three kinds of response views are distinguished: Simple object response Syntax: <object>simple Examples: Purchase Order Simple, Employee Simple Complete object response Syntax: <object> Examples: Purchase Order, Employee Freely defined object response Syntax: <qualifier>*<object>?<component>? The naming for a freely defined response views is identical as for service views. Page 87 of 113

88 4.9.9 Query / Response - Service Operation Syntax (outbound): <transaction activity><response view>by<selection criteria view> Syntax (inbound): <action><response view>by<selection criteria view> <transaction activity>: Action requested; allowed are Find, Query, Respond. <action>: Action offered (Find, Query, Respond) <response view>: Requested response view. See section <selection criteria view>: Name of selection semantics Semantical name (e.g. Planning Information) Sequence of main selection parameters concatenated by and Elements for maximal set of selection criteria Additional Rule for Core Queries For the naming part <transaction activity> only Query is allowed. The naming part <response view> is only allowed in case of content view. Examples: Query Purchase Order By Buyer Party Respond Purchase Order By Buyer Party Query / Response - Message Type Syntax for Query MT: <response view>by<selection criteria view>query Syntax for Response MT: <response view>by<selection criteria view>response <response view>: See section <selection criteria view>: Name of selection semantics Semantical name (e.g. Planning Information) Sequence of main selection parameters concatenated by and Elements for maximal set of selection criteria Examples: Purchase Order By Buyer Party Query Purchase Order By Buyer Party Respond Page 88 of 113

89 Query / Response - Message Data Type Syntax for Query MDT: <response view>by<selection criteria view>querymessage Syntax for Response MDT: <response view>by<selection criteria view>responsemessage <response view>: See section <selection criteria view>: Name of selection semantics Semantically name (e.g. Planning Information) Sequence of main selection parameters concatenated by and Elements for maximal set of selection criteria Examples: PurchaseOrderByBuyerPartyQueryMessage PurchaseOrderByBuyerPartyResponseMessage Special Naming Rule for the Element on BDO level for a Query: Syntax <response view>selectionby<selection criteria view> For all other IDT and element names see section , page 85. Example: MT Customer Invoice By ID Query is typed by MDT CustomerInvoiceByIDQueryMessage. The name of the IDT on BDO level is CustomerInvoiceByIDQuery The name of the element on BDO level is CustomerInvoiceSelectionByID Level 1 Level 2 MT MDT Element IDT Element GDT Customer Invoice By ID Query Customer Invoice ByIDQuery Message Message Header Business Document Message Header Customer Invoice Selection ByID Customer Invoice ByIDQuery ID Business Transaction DocumentID BDO UUID UUID Figure 38: Naming of Intermediate Data Types / Elements within a Query Message Data Type Page 89 of 113

90 Mass Messages Operation: Syntax (outbound): <transaction activity> <service view><mass processing type><action>? Syntax (inbound) : <action><service view><mass processing type> For A2X-Operations omit the BO name contained in the <service view>. Examples (outbound): 1. Request Purchase Order Change Bulk Change (transaction activity=request, service view=purchase Order Change, mass processing type=bulk, action=change) 2. Request Purchase Order Change Bundle Change (transaction activity=request, service view= Purchase Order Change, mass processing type=bundle, action=change) 3. Notify of Payroll Process Collection (transaction activity=notify of, service view=payroll Process, mass processing type=collection, no action) Examples (inbound): 1. Change Purchase Order Change Bulk 2. Change Purchase Order Change Bundle 3. Payroll Process Collection Message Type: Syntax: <service view><mass processing type><action>?<message type category> For synchronous operations and shortening rules refer to the basic naming rules for MTs. Examples: 1. Purchase Order Change Bulk Change Request 2. Purchase Order Change Bundle Change Request 3. Payroll Process Collection Notification Page 90 of 113

91 Message Data Type: <service view><mass processing type>message For synchronous operations and shortening rules refer to the basic naming rules for MTs. Examples: 1. PurchaseOrderChangeBulkMessage 2. PurchaseOrderChangeBundleMessage 3. PayrollProcessCollectionMessage <mass processing type>: Fixed term Bulk, Bundle or Collection <transaction activity>, <service view>, <action> and <message type category> as defined before Message-IDT: The name of a Message-IDTs follows the common naming rules described in chapter , page 85. Note: The Message-IDT on BDO level is, as a rule, reusable for typing of the BDO of a corresponding nonmass message, and thus, its name does not contain the <mass processing type>. Page 91 of 113

92 Reconciliation Messages Message Type: Dedicated reconciliation message types are named as follows: Syntax: <service view><action>?<message type category> <service view>: <action>: <message type category>: service operation view name consists of original view name followed by Reconciliation same as original (non- Reconciliation ) message type same as original (non- Reconciliation ) message type Example: Production Request Confirmation Reconciliation Notification (service view= Production Request Confirmation Reconciliation, message type category=notification) Page 92 of 113

93 Form and Interactive Form Form Message Type Syntax: Form<A2A/B2B Message Type> Form: <A2A/B2B Message Type>: Fixed term Name of corresponding A2A/B2B message type Interactive Form Message Type Syntax: InteractiveForm<A2A/B2B Message Type> InteractiveForm: <A2A/B2B Message Type>: Fixed term Name of corresponding A2A/B2B message type Form-Message Type - Intermediate Data Types Syntax: Form<GDT> For restricted GDTs <VARIABLE>_<GDT> (see GDT Guideline -> Restrictions on CDTs / GDTs ) the following syntax applies: <VARIABLE>_Form<GDT> Form: <GDT>: <VARIABLE>: Fixed term, omitted in element name Name of corresponding global data type that is extended to fit the needs of a form MT A variable is a special qualifier for a data type name that gets replaced in element names by an approved qualifier. Page 93 of 113

94 Create With Reference (A2X) Syntax for generic create operation: Message Type: Operation: <object>withreferencecreaterequest Create <object> With Reference Syntax for specific create operation: Message Type: Operation: <object>withreferenceto<refobject>createrequest Create <object> With Reference To <RefObject> <object>: <RefObject> Object to be created Object that provides information adopted for the creation of <object> Page 94 of 113

95 5 SAP Abbreviation Rules Naming rules for semantic names often result in names that are too long for dedicated name types such as: ARIS Name (length restriction 80) ESR Name (length restriction 120) Examples Business Object Node (length 88): Log Section Material Market Price Determination Explanation Derivation Step Output Price A2X Operation (length 122) AccountingCashLedgerAccountForeignCurrencyRemeasurementRunActionIn.ExecuteCashLedgerAccountForeignCurrencyRemeasurementRun Goal Create SAP wide unique abbreviations of high quality Outside-In driven Object Types that need to be abbreviated Object, Object Node Relationships Composition, Aggregation, Association, Association for Navigation Operations (Compound, Core) Message Type Data Type o Message Data Type o Node Data Type o Query / Action / Filter Data Type o Global Data Type o Intermediate Data Type Data Type Element Abbreviation Rules are applied for name types ARIS Name ARIS Technical Name (Length restriction implied by ESR) Page 95 of 113

96 5.1 SAP Abbreviations Guiding Principles Abbreviations are SAP wide unique o Guaranteed by using a common Abbreviation List o List contains only PIC approved abbreviations Abbreviations available as code list (GDT AbbreviationCode) Code list contains o Abbreviations for Individual terms (e.g. Arrgmt - Arrangement) o Acronyms (e.g. RFQ Request for Quote) o Abbreviations for Objects (e.g. CoTaxArrgmt - Company Tax Arrangement) Code List approved by PIC Request new abbreviations as new codes for GDT AbbreviationCode o Determination supported by KM General abbreviation rules describe aspects valid for all abbreviations Additional abbreviation rules describe aspects valid for dedicated object types and name types o Needed to fulfill requirements such as length restriction and readability needs 5.2 General Abbreviation Rules Always guarantee understand ability and distinguish ability of resulting abbreviations Try not to create abbreviations that are themselves English words An abbreviation is associated with only one unabbreviated word Do not use abbreviations that will conflict with commonly known abbreviations It is best to have an abbreviation begin with the same letter as the word being abbreviated Words that are four or less characters in length should not be abbreviated Page 96 of 113

97 5.3 Abbreviations in ARIS - Names and Length Restrictions Conceptional Modeling (no tool restrictions) ARIS Abbreviation rule needed Semantic Name Name according to naming rules No length restriction Identically taken over Name 80 Restricted to 80 Title Case as a rule UpperCamelCase for Data Types and Data Type Elements ( ESR) Technical Name max 120 Restricted to max. 120 depending on object type UpperCamelCase Motivated by need to link to ESR Full Name No length restriction Title Case Filled only if semantic name longer than ARIS Name - Abbreviation Rules For all object types the following naming rules are valid for the ARIS Name: Abbreviate from left to right, replacing terms by its standard abbreviation, until name length is less than 80 o Ensures that ARIS name is as understandable as possible o Abbreviated part of name contains no spaces; individual abbreviations start with upper case If the limit of 80 cannot be reached, abbreviate individually (without general rule) Example for Business Object Node: Semantic Name: (length 88) Log Section Material Market Price Determination Explanation Derivation Step Output Price ARIS Name: (length 78) LogSecMatl Market Price Determination Explanation Derivation Step Output Price ARIS Full Name: (length 88) Log Section Material Market Price Determination Explanation Derivation Step Output Price Page 97 of 113

98 5.5 ARIS Technical Name - Length Restrictions Overview Object Type Maximum Length Abbreviation Never Always As Required GDT 120 x Object To be decided x Object Node To be decided x Interface 60 x Operation 60 x Message Type 100 x Message Data Type 60 + Version x Intermediate Data Type 60 + Version x Node Data Type 60 x Table 3: Length Restrictions Overview Abbreviate Semantic Name for Technical Name Never: Semantic Name must not exceed the maximum length for Technical Name Always: Semantic Name is always abbreviated As Required: Abbreviate Semantic Name from left to right until name length fits 5.6 ARIS Technical Name: Abbreviation Rules For Interfaces, Operations, Node Data Types, Intermediate Data Types the following rules apply: A Length of Technical Name without namespace should never be longer than 60; abbreviate always B Applies only for IF / Operation: Leave out duplicate parts of the semantic name Make sure that the name still expresses the right semantics C Applies only for IF / Operation: Abbreviate the Process Component by its four letter abbreviation D Applies only for NDT / IDT: From the semantic name leave out the path leading to the node If the result is not unique within the object or MDT add the differentiating part of the path leading to the node Page 98 of 113

99 E Replace terms by its standard abbreviation Individual abbreviations start with upper case If needed, request for missing abbreviations via PIC process F If the limit of 60 cannot be reached abbreviate individually (without general rule) Note: Namespaces should be as short as possible. New namespaces should not be longer than 30 letters Page 99 of 113

100 Examples: A2A Operations Semantic Name (without spaces): CustomerInvoiceProcessingRequestInvoicingIn.MaintainCustomerInvoiceRequest (74 characters) After rule C: CIV_RequestInvoicingIn.MaintainCustomerInvoiceRequest (53 characters) After rule E: CIV_ReqInvcgIn.MaintCustInvReq (30 characters) Semantic Name (without spaces): BalanceOfForeignPaymentManagementForeignReceivablePayableNotificationIn.CreateForeignReceiv ablepayable (102 characters) After rule B: BalanceOfForeignPaymentManagementForeignReceivablePayableNotificationIn.Create (78 characters) After rule C: BFP_ForeignReceivablePayableNotificationIn.Create (49 characters) After rule E: BFP_ForgnRecvbPaybNotifIn.Create (32 characters) Semantic Name (without spaces): LogisticsExecutionControlFulfilmentIn.ChangeLogisticsExecutionRequisitionBasedOnDeliveryFulfilme ntconfirmation (110 characters) After rule B: LogisticsExecutionControlFulfilmentIn.ChangeRequisitionBasedOnDeliveryFulfilmentConfirmation (92 characters) After rule C: LEC_FulfilmentIn.ChangeRequisitionBasedOnDeliveryFulfilmentConfirmation (71 characters) After rule E: LEC_FulfilmentIn.ChangeReqiBasedOnDelvFulfConf (46 characters) Page 100 of 113

101 Examples: A2X Operations Semantic Name (without spaces): CustomerInvoiceProcessingManageCustomerInvoiceRequestIn.CreateCustomerInvoiceRequest (84 characters) New pattern definition without repeating the object name: CustomerInvoiceProcessingManageCustomerInvoiceRequestIn.Create (62 characters) After rule C: CIV_ManageCustomerInvoiceRequestIn.Create (41 characters) After rule E: CIV_ManageCustInvReqIn.Create (29 characters) Semantic Name (without spaces): AccountingCashLedgerAccountForeignCurrencyRemeasurementRunActionIn.ExecuteCashLedgerAcc ountforeigncurrencyremeasurementrun (122 characters) New pattern definition without repeating the object name: AccountingCashLedgerAccountForeignCurrencyRemeasurementRunActionIn.Execute (74 characters) After rule C: ACC_CashLedgerAccountForeignCurrencyRemeasurementRunActionIn.Execute (68 characters) After rule E: ACC_CshLdgrAcctFrgnCrcyRemsmtRnActionIn.Execute (47 characters) Example: Node Data Type Semantic Name (without spaces): US_EmployeeTaxArrangementFederalTaxArrangementTaxAuthorityItemPeriodTermsLocalityAddition altaxeselements (104 characters) --BO Node > --Node > -Node3-----> -Node4> -- Node5-----> After Rule D: Page 101 of 113

102 US_EmployeeTaxArrangementLocalityAdditionalTaxesElements (56 characters) After rule E: US_EmplTxArrgmtLoclAddTxsElmnts (31 characters) Example: Intermediate Data Type Semantic Name (without spaces): US_EmployeeTaxArrangementPayrollNotifiactionFederalTaxArrangementTaxAuthorityItemPeriodTer mslocalityadditionaltaxes (115 characters) --MessageType > --Node > --Node > -Node > -Node4-> --Node5----> After Rule D: US_EmployeeTaxArrangementPayrollNotifiactionLocalityAdditionalTaxes (67 characters) After rule E: US_EmplTxArrgmtPayrlNotifLoclAddTxs (35 characters) Page 102 of 113

103 5.7 ESR Name Adopted from ARIS Technical Name The ESR name is identically taken over from ARIS Technical Name. The Length restrictions are in ESR is identical to the length restriction of the ARIS Technical Name. In case a deviating ESR name already exists and adoption is not feasible anymore, proceed in the following way: Only in that case: Fill ARIS Technical Name with the existing ESR name Set ARIS Flag Keep Technical Name to avoid overwriting Reason: ESR Name has to be identical to ARIS Technical Name to ensure error detection by ESR-ARIS check. Page 103 of 113

104

105 6 SAP Object Model - Documentation Business Objects are an approach to model real world business content. A Business Object represents a view on a well defined & outlined business content o Well known in the business world (for example, in an international standard or industry best practice). a self-contained (capsule), independent business concept The objects of the SAP object model are classified in the following way: Business Object o o Business Foundation Object Business Transaction Object Technical Object Transformed Object Mass Data Run Object Offered service operations reflect the expected business needs to access or manipulate the object (or parts of it). Object Capsule Root <Object> Root <Node 1> <Node 1_1> <Object> <Specialisation> <Node 1_2> <Object> Root <Node 2> Figure 39: Components and Environment of an Object Figure 39 shows the model of an object with its components and environment. The object itself is a capsule hiding its internal structure and offering compound service operations. The internal structure of a business object refines the object into semantic components (nodes, subtypes, elements, relationships) according to the business understanding. Page 105 of 113

106 For a holistic documentation of an object the following entities are to be described: Object o Object Name BO Documentation o Object Definition -Name o Process Component - Definition - Process Component o Deployment Unit - DU - Nodes / Subtypes Object Capsule - Compositions / Associations o Nodes / Subtypes - Integrity - Business Object Environment - Node Element Structure o Compositions / Associations - Interfaces / Operations o Integrity Business Object Environment o Inbound Association o Inbound Aggregation Node Elements Structure Interfaces / Operations o Core Service Operations ( Actions, Queries ) o Compound Service Operation ( B2B / A2A / A2X, Inbound / Outbound ) For the definition of an object and the entities it consist of the rules presented in this guideline apply. Special hints are presented in the following sub sections. Page 106 of 113

107 6.1 Target Group Specific Pattern-Based Documentation To get understandable objects, a holistic semantic documentation of the objects with its services is required. The documentation should be concise but sufficient and adequate for the respective target group. Depending on the target group focus and granularity of object documentation may differ. A way to get a target group specific documentation is to create a common documentation and to generate target group specific documentations using filters. For example business object documents can be generated for the different review types (PIC 1, PIC 2, PIC 3) containing only the granularity of information needed for review but always containing a complete holistic documentation of the business object. This documentation describes the objects and services as a whole, as well as defining its substructures. All structure elements are explained by documentation that Describes the structure and environment Specifies integrity conditions and Refers to the data types used As the building blocks of the objects and services are the same, its documentation is pattern-based. A document pattern not only specifies the basic document structure but also text blocks or uniform phrases for all object / service documents (analogous for data types). Figure 40: Pattern Based Documentation of Objects An object documentation is a Central self contained document for design / review / roll out Generated from ARIS Growing during PIC 1/2/3 process Page 107 of 113