Database Management (Functional) DELMIA Apriso 2018 Implementation Guide

Transcription

1 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 2017 Dassault Systèmes. Apriso, 3DEXPERIENCE, the Compass logo and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA, NETVIBES, and 3DXCITE are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.

2 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 2 Contents 1 Introduction Purpose Scope Intended Audience Definitions 3 2 Databases 5 3 Tables Type of Keys/Unique Identifier Table Structure 6 4 Database Upgrade 8 5 Data Protection 9 6 Database Documentation Application 10 7 Extending DELMIA Apriso Database General Rules Creating Custom Tables Required Columns Foreign Key Constraints Creating Indexes and Triggers Creating Stored Procedures Validation Passing NULL Parameters Concurrency Control Naming Convention for Custom Database Objects Reusable Objects Project-Specific Objects 14 8 Special Features Text Management Text from SAP Time Zone Management Special Types of Users Download from ERP For the Labor and Attendance Data Table Triggers 16 9 References 17

3 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 3 1 Introduction 1.1 Purpose The purpose of this document is to provide key information about how data is managed and stored in the DELMIA Apriso databases. 1.2 Scope This document covers the following areas: The purpose of the various DELMIA Apriso databases The various types of tables The various types of keys and other unique identifiers The typical structure of the tables How Database Upgrader works How to protect data (reserved tables, reserved ranges, etc.) How to use the database documentation How to extend the tables Special features 1.3 Intended Audience This guide is intended for all the people who use DELMIA Apriso data. 1.4 Definitions MODEL data all the data that belongs to the MODEL database. These are the categories of MODEL data: PRIME (previously referred to as PRIMING, and this name may still appear) this kind of data is fully controlled by the DELMIA Apriso application, and it may be removed, changed, or added by the Database Upgrader The user should not make any changes to this data. INIT this kind of data is initially loaded during the installation or upgrade process, but it may be changed by the user Once it is created, the data is not updated by the Database Upgrader DLL this data is dynamically created in the database by scanning the DLLs that exist in the user environment TEST this data is for testing scenarios, and it may be removed DEMO this data is for demo scenarios, and it may be removed

4 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 4 Only PRIME, INIT, and DLL are required to run the application. The names of the categories related to the classification of MODEL data are always written in all upper-case letters (that is, MODEL, PRIME, INIT, DLL, TEST, DEMO). MODEL database this is the database that contains the complete schema and all the MODEL data required by the specific version of DELMIA Apriso. It does not contain any operational data. A MODEL database has the suffix M in its name. There is a separate MODEL database for all the combinations of the DELMIA Apriso database, the Framework database, and MSSQL and Oracle environments. The MODEL database is the only official pattern of the database schema delivered by PD&R. This is the only database that can be used to create a newer version of the database or a test database for product management.

5 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 5 2 Databases DELMIA Apriso usually uses two to three databases: The Main database The purpose of this database is to persist all the live data, master data, system configuration, and history data The Framework database The Framework data contains only the literals (as in, what is displayed on most of the screens) The Archiving database (optional) The Archiving database has the same structure as the Main database except that no foreign key exists between the tables The data is copied using the Archiving framework from the Main database to the Archiving database With the DELMIA Apriso DVD, Dassault Systèmes provides two databases for each supported DBMS: The MODEL database (on the Install DVD) The Business Process Flow database (on the Business Process Flow CD) From the Install DVD: The MODEL data (created by the user MODEL): The MODEL database contains some data to allow the customer to do a quick start (e.g., some employees, Facilities, products, locations) The MODEL database can be cleaned during the installation process so that only the PRIME and the INIT data remain The result of the cleanup is named the PRIME database The PRIME data (created by the user PRIME): The PRIME database contains only one user, no Facility, no product, etc. This is a clean database that has to receive some customer content in order to be ready to go in production This database contains the PRIME data that might be modified, depending on the tables Dassault Systèmes can update the PRIME data, but the INIT data is only inserted and will never be updated after creation From the Business Process Flow CD: The Business Process Flow data: The Business Process Flow database is built on top of the PRIME database and contains the data needed to run the DELMIA Apriso Business Process Flows

6 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 6 3 Tables Table records can be added and modified but should not be removed. For details, see 5 Data Protection. The User tables contain live data that will not be updated by Dassault Systèmes (these contain only customer data). 3.1 Type of Keys/Unique Identifier Customer data is not updated by Dassault Systèmes upgrades. The way that data is protected depends on the type of unique identifiers used: ID the key of the table is an incremental ID Once released, DELMIA Apriso databases are set up to have IDs that are higher than 100,000,001 DELMIA Apriso databases used to maintain data that is required for the system have IDs from 1 to 100,000,000 When the Database Upgrader runs, it inserts the record in the range that is not used by the customers (that is, 1 to 100,000,000) FUID the DELMIA Apriso unique identifier The FUID is a unique identifier linked to an entity when it is created and is an attribute of some DELMIA Apriso tables The key of these tables can be the ID or another type of entity The FUID is unique across the network. Usual data element key a combination of one or more elements of the character or integer type 3.2 Table Structure In addition to the key and the data in the table, each table contains a list of the fields that help the tracking activity: REFERENCEID not currently used LASTUPDATEON the time (in UTC) that the record was last updated LASTUPDATEDBY the person who last updated the record CREATEDON the time (in UTC) at which the record was created CREATEDBY the person who created the record ACTIVE a Boolean flag that determines if the record is active LASTDELETEON not currently used LASTDELETEDBY not currently used LASTREACTIVATEON not currently used LASTREACTIVATEDBY not currently used

7 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 7 ARCHIVEID not currently used LASTARCHIVEON not currently used LASTARCHIVEDBY not currently used LASTRESTOREON not currently used LASTRESTOREDBY not currently used ROWVERSIONSTAMP the current version of the record, used for concurrency validation The above fields are commonly referenced as "WHO columns."

8 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 8 4 Database Upgrade The upgrader updates the database to the time of the upgrade. The purposes of such upgrades are to: Add/modify table structures in order to support new features Update table contents in order to provide backward compatibility Add records to the database so that new features can be used (e.g., menu items, types) It is critical that customers manage their data in the right way so that the Database Upgrader does not overwrite the data during the upgrade. For more information on the Database Upgrader, refer to the Database Upgrader Online Help.

9 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 9 5 Data Protection The way that data can be protected depends on the types of tables and unique identifiers. The following rules apply to shared tables (in this sequence): 1 A table managed with FUID and PDC (e.g., Processes, Operations): a Each entity is uniquely identified by an FUID. To avoid updates of Processes coming from Dassault Systèmes, the only action is to create a customer copy of the Operations used in production to make sure they will not be overwritten. 2 A table managed with an ID: a When the DELMIA Apriso Database Upgrader runs, it inserts records in the range that is not used by the customers (1 to 100,000,000). 3 A table managed with an Integer as a key (types as an example): a The user should create records with a value higher than 999,999 in order to avoid overwrite by the DELMIA Apriso Database Upgrader. 4 A table managed with a Character field as a key: a The user should implement a naming convention in order to avoid records to be updated by the DELMIA Apriso Database Upgrader (e.g., no use of FLX_, APR_). We usually recommend using three letters as a prefix. b In order to see the current list of system tables and views (that are not to be changed by the customer), run an appropriate query on the database. For example, on SQL: Select * from information_schema.tables

10 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 10 6 Database Documentation Application The Database Documentation application allows you to easily comprehend the DELMIA Apriso database structure and the purpose of the various tables and fields. The database documentation application contains the following information: At the category level (as in, the grouping of tables per functional area): An ER diagram of the tables involved At the table level: The table description and purpose The value of the PRIME data delivered with the table At the field level: The purpose of the field The Database Documentation application was developed for customers to be able to easily view the tables in their own database. Therefore, a script (Upgrader) was attached to the application that makes it possible to refresh both tables and the structure in which they are organized (that is, the browser tree). The update script in launched by an EXE file that can be found in the Database Documentation folder. For details, see Database Documentation.

11 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 11 7 Extending DELMIA Apriso Database 7.1 General Rules The DELMIA Apriso database can be extended by custom database objects. The list includes: Tables Views Stored Procedures Functions Indexes The main requirement for any modification of the DELMIA Apriso database is that standard schema objects should not be renamed, modified, or deleted as this would cause Database Upgrader to fail. Only standard indexes can be removed. 7.2 Creating Custom Tables Required Columns The following columns should exist in each custom table (and also in all standard tables): The automatically incremented ID of the row The ID column must be first column in the table The initial value should be 100,000,000 All the user-created records in the tables MUST have IDs greater than this value. Records with IDs below that value are reserved ONLY for Dassault Systèmes, but please be aware that there are cases where standard product records can have their IDs in any range. A set of unique columns that unambiguously determine the row (required by GPM to move custom business entities if configured) A column with the GUID should have the name FUID and the type of nvarchar(36), not null ReferenceID int LastUpdateOn datetime LastUpdatedBy nvarchar(50) CreatedOn datetime CreatedBy nvarchar(50) Active bit, default value 1

12 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 12 LastDeleteOn datetime LastDeletedBy nvarchar(50) LastReactivateOn datetime LastReactivateBy nvarchar(50) ArchiveID int LastArchiveOn datetime LastArchivedBy nvarchar(50) LastRestoreOn datetime LastRestoredBy nvarchar(50) RowVersionStamp int, default value 1 A custom table must have either none of the WHO columns or a complete collection of the WHO columns so that the upgrade process can finish successfully. 7.3 Foreign Key Constraints When the column name ends with TextID, it is automatically treated as a reference to the TEXT_TRANSLATION table Such columns should not have any foreign keys constraints When a column is named UnitID, it is automatically treated as linking to the UNIT table When the user creates a child table that links through a foreign constraint to one of the standard DELMIA Apriso tables, then upgrade problems may appear when a parent table is changed Such problems must be handled manually by the user 7.4 Creating Indexes and Triggers The user can create additional functional indexes for improving the speed of access to certain standard and custom DELMIA Apriso database tables. The user is also allowed to remove standard indexes. Creation of triggers on DELMIA Apriso tables is allowed, but please note that this is not recommended. Triggers perform actions implicitly in the background and therefore make the diagnosis of potential problems in the system more complicated. Other modifications on standard DELMIA Apriso tables are not allowed. When new indexes are created for standard DELMIA Apriso tables, the execution plans and performance of queries used by standard Business Components and other elements of the system may be affected.

13 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide Creating Stored Procedures Validation The Stored Procedures should perform at least the basic validation of passed parameters in order to maintain the consistency of the database. Optionally, custom business rules may be applied to verify the data Passing NULL Parameters All the Stored Procedures are intended to be called from DELMIA Apriso. Because DELMIA Apriso cannot currently pass NULL parameters, all Stored Procedures may treat the following values as NULLs: Integer 0 Decimal 0 Char empty string DateTime 2000/01/01 12:00 AM Boolean cannot be null Concurrency Control The Stored Procedures should be written using the optimistic concurrency control (the same as in standard DELMIA Apriso). This means that the RowVersionStamp column should be checked to determine if the record used in the transaction has been changed in the meantime. If a change is detected, the Stored Procedure should return the Table XYZ concurrency violation error code. 7.6 Naming Convention for Custom Database Objects Custom database object names must not conflict with existing objects and words reserved by SQL. However, keeping a convention defined in the subsections below in order to prevent future problems is recommended. When the name of an object is in conflict with a word reserved by SQL, the name should end with an underscore ( _ ). Example: JOIN_, PROCEDURE_ Reusable Objects This naming convention for custom database objects is used by DELMIA Apriso Professional Services (such objects can be reused across multiple projects): AX_ObjectName_[Internal] AX object type descriptor, depending on the X value: P Stored Procedure F Function T table V view

14 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 14 I index ObjectName the name of the object describing its functionality Internal an optional suffix indicating that the object should not be used directly from Apriso and it is only for internal Framework purposes For example: AP_MoveMultilevelContainer AT_InventoryCountHeader Existing objects starting with an AX_ prefix should not be changed in order to maintain compliance with future versions. New AX_ objects can be created in the future by implementation teams and delivered as a reusable library Project-Specific Objects This naming convention can be used for custom objects that are project-specific and the intention of author is not to share them in other implementations: PPP_ObjectName_[Internal] PPP the abbreviation of the project name ObjectName the name of the object describing its functionality Internal an optional suffix indicating that the object should not be used directly from DELMIA Apriso and it is only for internal Framework purposes For example: ACME_CreateOrder ACME_Report_Production

15 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 15 8 Special Features 8.1 Text Management DELMIA Apriso can support data documented in multiple languages at a time. The data structure to support this feature is the following: Entities that contain a localized description contain a field named TextID The TextID is defined as the ID of the table named TEXT The ID of TEXT is used in the table named TEXT_TRANSLATION The TEXT_TRANSLATION table contains the language (LanguageID) (one row per text and language) The TEXT_TRANSLATION table contains multiple text fields, from very small (micro) to very large (extended) as well as the ability to store links to icons and URLs. 8.2 Text from SAP Mapping SAP text can be complex due to the way data is persisted in the XML message. The recommended mapping uses the following structure: The entity (e.g., a product) is linked to a record in the TEXT table (Text.ID = Product.TextID as an example) Mutilple Text.Detail exist for each Text. (one for each type of text in SAP) (Text.ID = TEXT_DETAIL.TextID) Mutiple Text_Detail_Translation records exist (one for each line of text and language in SAP) 8.3 Time Zone Management For all areas except labor/attendance data: DELMIA Apriso persists data in most of the tables in UTC time and prompts/displays the data in the user time The presentation layer manages the conversion (Process authoring and Maintenance screens) The Business Components assume that the times they receive as Inputs or Outputs are in UTC The time zone definition for a user is defined in the user personalization By default, the time zone assigned to a new user is the one defined as the default time zone in the Central Configuration file

16 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide Special Types of Users Background users (Background Job Processing): the background processes are associated to the valid users defined in the DELMIA Apriso database. The assignment of users to background processes is done in the configuration files. The user time zone of the background users can also be overwritten in the configuration files Download from ERP XML manager also has to process some data time conversion. The conversion is in this case not based on the user that processes the integration, but on the time zone of the external system. The time zone of the external system is defined in the configuration file For the Labor and Attendance Data In most of the tables that are involved in labor- and attendance-tracking areas, both local and UTC time is persisted. Some tables like SCHEDULE only have local. 8.4 Table Triggers Table triggers cannot modify the values of the RowVersionStamp column. The value of RowVersionStamp is used by the concurrency check engine and can only be modified by DELMIA Apriso components.

17 Database Management (Functional) DELMIA Apriso 2018 Implementation Guide 17 9 References All the documents referenced below are available from the DELMIA Apriso Start page, which can be accessed on your DELMIA Apriso server (<server name>/apriso/start). The newest versions of all the documents are available from the 3DS Support. 1 Dassault Systèmes, Database Upgrader Online Help This Help presents an overview of the Database Upgrader tool. It provides the background information necessary for using the product and describes how to carry out common tasks. 2 Dassault Systèmes, Database Documentation This standalone Web-based application enables the easy viewing of DELMIA Apriso database tables (organized into groups), their descriptions, and the relations between them