M3 Customer-Defined Fields (CDF)

Background

M3 Business Engine has various user-defined fields for select types of information. These are, however, limited in types and are often too few to cover all needs. The CDF functionality are added to complement these and to minimize the need for modifications to add additional information to the M3 database.

Definition of CDF

The metadata that defines the CDF to be used is added through the program 'Customer-Defined Fields. Open' (CMS080). The metadata includes a selection of the M3 table to extend (see below), the type of information (string, numeric information, etc.), as well as the used length, number of decimals, etc. The user also sets the description of the CDF that is used as column headings in lists, reports, etc.

The initial selection of this information is done by the user selecting a field in the drop-down list that is as close as possible to the final definition. The user can select from various types like check boxes, dates, and numeric fields, as well as various lengths of alphanumeric fields.

Note that the metadata for the CDF must be defined for information to be added to a field in the CDF tables, or the CDF information to be used in the M3 lists, reports, etc.

Adding CDFs to extend the M3 standard information

The user specifies the name of the M3 table to extend and then selects the type of field to use.

Adding CDFs not related to M3 standard information

This type of CDFs is used to store information not connected to or directly related to the standard M3 information. It is also used to store related information that needs additional or fewer keys than the standard M3 information.

To add this type of CDFs, the user selects a table where the information is to be stored (CUGEX2 or CUGEX3) and secondly defines the ID of the information, in form of the customer extension reference, before selecting the type of field to be used. The customer extension reference is later used as the key to separate different information stored in the same table. This should be named in such a way that makes it easy to know which type of information that is stored.

Definition of valid values

The CDF definition can also include rules for validation of entered values. This includes a valid range and a multiple for numeric values (for example, valid values are 4–12, but each value must be evenly divisible by 4, meaning only 4, 8 and 12 are valid), as well as a list for both numeric and alphanumeric values. The latter is maintained through a separate program: 'Customer-Defined Fields Value Map. Open' (CMS081). Note that an entered value for a date of the type CDF must exist as an active date in the M3 system calendar.

Maintenance of CDF fields

Information stored as a CDF are maintained through the CDF API (CUSEXTMI). The API performs validation according to the rules defined in the CDF metadata. The information is then also conformable to the established way of storing it in the M3 database.

Usage of CDF fields

The information stored as CDF fields can be used as a part of M3 without any need for special coding or modifications. The exception to this is if the CDF must be added to a detailed M3 Business Engine panel, or used as part of existing or new business logic.

• Use CDFs in configurable lists, custom lists, configurable XMLs, and Ad Hoc reports

  There are two different use cases described below:

  1. CDFs already exist when list or report is created

     When a new configurable list or report is created, already defined CDFs for the master table of the list/report are automatically added to the list or report as available fields. They are directly available when the user defines the columns in the list or report. If a new CDF is later added to the master table, it must be manually added as an available field (this is performed from the definition of the related tables).

  2. CDFs are added after a list or report is created

     When CDFs are added to the master table of an already existing list or report, they must be manually added as a related table to each list and report where they are to be used. The user adds the CDF table (CUGEX1) and verifies the defaulted values. The same process must be used for addition of CDFs not related to the master table. The only difference is that the user must know whether the CUGEX2 or CUGEX3 table is to be used. The user must also select the extension reference that is to be used to retrieve the correct information.

• Use CDFs in API and search-based prompt

  The CDFs are managed in the same way as above also for API transactions through CMS100MI and the search prompt. These are both based on the custom list program 'Information Browser Category. Open' (CMS010).

• Use CDFs in older not configurable lists

  This is currently not supported and due to performance issues, it is not recommended to use a UI script to solve this. One work-around can be to create a new list for the used table through the custom list in (CMS010).

• Use CDFs on detailed M3 panels

  This is currently not supported. The recommended solution is to use a UI script that retrieves/updates relevant information through CMS080MI and CUSEXTMI.

• Use CDFs in M3 Mashup

  The recommended solution is to always use the CDF API (CUSEXTMI) to manage the information and to perform any maintenance on the stored information.

• Use CDFs as part of M3 business logic

  This requires a modification to the code. An alternative is to code the functionality outside the M3 standard through other coding frameworks including Mongoose, etc. Any information updating the M3 CDFs is added through the CDF API.

• Use CDFs with Enterprise Search

  The CDF information is part of the standard set of data indexed in IES and can be used for filtering without any specific requirements. Note that the indexed tables contain information for many extended tables or different types of not related data. To eliminate false hits, the search query should always include the name of the file or the extension reference. Also note that 'Key Search. Open' (CMS030) must be used for a search for CDFs. A specific key search should be created per table extension and embed the used table name as part of the predefined query in the key search. Aliases must also be created in 'Field Alias. Open' (CMS031) as a translation between the standard table keys and the extension table keys. The aliases should be limited to the key search for the CDFs for a specific table.

Technical storage of CDF in the M3 database

The information stored as CDFs are managed by three special CDF tables in the M3 database. Thus, the CDF information is not stored in the original table if it is used to extend a standard table, but retrieved in a separate database access. These are the names of these tables:

• CUGEX1: Used to extend M3 standard tables with CDFs
• CUGEX2: Used to store not M3-related numeric information
• CUGEX3: Used to store not M3-related alphanumeric information

The information stored as CDFs are stored in the M3 database in the CUGEX1 table for extended tables, or in CUGEX2/CUGEX3 for not related information. The CDF information is stored in the fields selected in the definition of the CDFs. The extended information in the CUGEX1 table is stored with the name of the extended table as the first key (in the FILE field). The rest of the keys are set identically to the primary key of the extended table. The unrelated information is either stored in CUGEX2 or CUGEX3 depending on the selection when the CDF was defined. The second key is the customer extension reference that was also selected during definition. The other keys are controlled by the update and not validated.

Limitation

As a maximum, the CDFs can use eight keys to separate information. This means that M3 tables of more than eight primary keys cannot be extended.

Customer-defined fields (CDF) have a restriction to enforce its usage to master data tables only. You see error and warning messages when creating or updating CDFs that target transactional data tables.

Importing and replacing an existing record in (CMS080) with a different definition might cause non-matching of data in the Customer extension file table (CUGEXn).