Skip to main content
Skip table of contents

Entities

Basics

In the Entities node, additional objects (”Customized Entities” so-called C2 entities) can be created in the database and linked with other objects (entities).

Figure: Entities

Hint

Save your database before you create a C2 entity.

Create new entity

This is how you create a C2 entity (basic process):

1.

Opening the node Entities implicitly leads to the new creation mask for a C2 entity. With the button New button, you can create a new entity if you previously loaded, for example, an existing C2 entity. The input fields for the entity name and entity label are already filled with C2. Simultaneously, a text field with the description Pk already exists in the field list on the right side of the mask. This field will later include the primary key from the table and cannot be removed or edited.

2.

Create a unique name for the new entity. Remember that the name begins with the character combination C2. This is an internal convention to be able to identify individually created entities by name. If you try to enter a name without C2 in the beginning, the background color of the input field will change. The name of the entity remains in the program later, the user only sees the entity label.

A total of 15 font properties can be entered in the EntityCreator, the first font properties must be used for identification:

  • Cxx / C2 (where xx is the two-digit partner number)

  • 12 or 13 font properties are provided for free input of the name

3.

Under entity label, enter the desired description just as it should appear later in the system.

  • The entity label is possible in multiple languages even though the label field is only present once. Log in as an administrator in German and enter the label, the label will apply to clients in German. If you would like to set the label for English clients, then you have to log in as an administrator in English.

  • You can change the label retrospectively.

4.

The two checkboxes Main Mask and Submask allow you to determine, whether the newly created entity can be invoked later as a main entity, if it should only be a linked sub-entity for e.g. a business partner, or both.

5.

Clicking the button Icons for the entity will load the icons for the new entity. Permitted formats are: gif, jpg and png.

Load the icon in 5 resolutions:

  • 16x16 pixels

  • 24x24 pixels

  • 32x32 pixels

  • 128x128 pixels

  • 256x256 pixels

The name of the file should be structured as follows:

<Name><Resolution>.<Extension>.

image2020-4-6_9-3-5.png

6.

Add new fields to the entity as needed via the toolbar:

  • Single fields

  • Key fields

  • Lookup fields

The field names (also known as “column names”or “table column names”) may only be up to 15 characters long.

7.

Set the links via the checkboxes in the area Linked entities. The settings made here have effects on the reachability of the new entity. For example, a new object Additional information is created with the attributes Main mask and Sub-window and only linked with the existing Contact Person entity. The additional information may only be accessed later for each contact person in the sub area. If you open the main mask additional information, the linked contact person can be shown for any information.

The assignment to other entities can be changed retrospectively.

8.

A configuration can first be examined without saving. You can access the check function via the Check button

9.

After you have created all required fields in the list without errors, the entity must be saved. This is done via the button

. If there are errors in your configuration, a message will inform you of this. The configuration will not be saved then. The error must first be fixed for you to successfully save the configuration. Additional system-related fields are added while saving.

Note

If the entity was saved, the button

  • (Removes all fields) and

  • (Remove all selected fields)

will be shown in gray. These functions are no longer available. Once fields have been saved, they may no longer be deleted. This is possible only via an SQL statement.

10.

After the new creation of an additional entity, you need a graphic interface (mask). It is created via the GUI Builder. You can start this module directly via the corresponding button

in the toolbar. The GUI Builder loads the newly created entity directly. You can find out more information about this in the chapter GUI Builder.

11.

A default search for the newly created entity must also be created. This is done via the administration console and the node field attributes. You can find further information about this in the chapter Field properties. A field for the generated default search should be activated as Search field. If the search result field option was activated, the field will appear in the search mask as a column.

12.

With the button

you can change to the Mask Configuration node, where you enable the new mask (checkbox in the column Main Mask).

The button is only active if a saved entity has been loaded.

13.

The definition of an additional entity can be saved to an external file or loaded from an external file to use for a transfer to another application. This is done via the buttons Import and Export in the toolbar.

14.

The client must be restarted to save the settings.

Single fields

These are fields that should only save data from a mask. If the button is pressed, a new field will be created in the field list with the description NewField. Enter a new name for the field in the Field column. Please remember that no spaces or special characters must be used. You can now select the desired file type for the field via a drop-down list in the column File type. Text fields, Number fields, Date fields and Memo fields, as well as fields for logical values are differentiated. The Length column has a size of 255 characters by default. This size can be changed individually when creating a text field. In the Display name column, a different name can be entered for the field. Spaces and special characters may also be used here.

Key fields

Note

The key field should be of type String. The internal logic assumes that the lookup fields are text or number fields. Key fields may not immediately lead to errors, but they are susceptible, because the programming does not assume that this type is saved there.

The dialog to create a key group is opened first when a new key field is created.

Figure: Key group creation

Figure: Key group creation


Give the new key group a name in the Value field and a clear description that can be used to later identify the key for maintenance. The checkbox Double-sided key allows you to define, whether the key is a regular lookup key or a key with a double relation similar to the function Company Parent to Company Affiliate. The checkbox Keys are new groups allows you to determine, whether the key should be a multi-level key with sub groups. All further creation is similar to the creation of single fields.

Lookup fields for other entities

When creating this type of lookup field, you have to select the data field of another entity first, where the lookup will later be done. Two steps are needed for this:

Selecting the database entity:

Figure: Lookup field creation - entity selection


A relevant message will appear if there are already some default searches defined in the system for the selected entity (e.g. employee).

Figure: Lookup field creation - message


If that is the case, then the specified lookup definitions can only be applied as follows:

Figure: Lookup field creation - applying existing lookup definitions


The selection dialog will appear to specify the lookup fields if no lookup definitions were previously saved in the system for the selected entity:

Figure: Lookup field creation - selection of lookup fields


Individual fields can be selected or deselected via the middle buttons Assign and Remove assignment.

Image fields

You can place image fields on the mask using the “Image” field type (RecordableImageSelectionField) in the C2 entities.

Figure: Image field on the mask of a C2 entity


You can define the size and resolution of the image via the field attributes. Place the fields on the mask using the GUI Builder (administration rights are needed). The user can edit these defined fields by clicking the mask.

Deleting a relation and security prompt

When a relation is removed in the EntityCreator, the user will receive a message under the following conditions.

  • The relation is created with a different name when it is clicked again.

  • The relation contains data.

Only one of the two messages may appear, depending on the available data.

CSV import of tables for C2 entities in EntityCreator

If the requirements are implemented, the defined fields must be created manually by the person responsible using the EntityCreator of the administration console. These are often entities that should have a large number of fields, so that a considerable amount of time is required. A CSV template, in which the internal field names, data types of the respective fields, field lengths and display names are maintained, can be used by an export from the Word file and conversion for this. The fields are created via an import in EntityCreator and then saved regularly. In this way, the effort for creating new entities can be reduced.

Furthermore, the internal field names, data types, field lengths and display names can be exported as CSV by the EntityCreator for documentation purposes. An extension of an entity by additional fields is also possible with minimal effort.

0023436 Felder aus CSV laden.png

Figure: Button for import of a CSV template

A predefined CSV template exists in which the fields to be created can be maintained for the C2 entity to be created. The button is only active on C1 and C2 entities. By clicking the button, the FileBrowser opens for selection, the only permissible import format is .csv. After selection of the file and confirmation of the dialog by the administrator, the file is processed. If the import contains key or lookup fields, a message appears.

Empty field names and empty data types are ignored during import. For empty I18n values, the field name is used. Information such as name, label, shortcut and icon of the entity, main mask and sub area must be entered regularly by the administrator via the EntityCreator. The assigned entities must also be maintained manually by the administrator. The validation of the entries made (field names reserved by the system, length restriction, invalid field names, completeness of entries, duplicate fields) takes place during the storage attempt in the EntityCreator. If the validation is successful, the entity is created including the specified fields. If validation fails, the saving process is aborted.

Entity for buffering data

With the entity cache a generic possibility was created to temporarily store data that requires a lot of time and/or computing power to determine in order to use this data later (e.g. for tiles, scripts). Data is provided with a possibility to be valid for a limited time.

Buffering is also possible from database scripts.

Technical field name

Dept. Field name

Data type

Description

TextValue

Text value

Memo field

  • Professional value as string

  • Explicitly defined as memo field, so that also large text (JSon structures) can be stored

NumberValue

Double

Decimal number

  • Professional value as a number

Id

Dept. ID

varchar(255)

  • Professional ID for this entry

  • Mandatory field

  • Unique Field = true

ExpiresAt

Valid until

Datetime

  • Time until which this entry is technically valid

DateValue

Date value

Datetime

  • Professional value as a date

BooleanValue

Yes/No value

Boolean

  • Professional value Yes/No

General access

  • In principle, the entity can be accessed via the normal BPM possibilities (WorkSpaceScriptUtils ...).

  • The access, especially in tiles, is done via the available options (usually search, if required encapsulation in BPM processes or separate script library methods)

Provision of Util methods

  • The methods described below are to be provided to a ResultStoreUtils Util class and are intended for simplified use for the classic application purposes

  • They are de facto only wrapper methods around the WorkSpaceProxyUtils Util class. It follows that

    • the methods described below can be used wherever the WorkSpaceProxyUtils Util class can be used

    • the normal BPM events are triggered when data in the "cache" entity is changed

Definition methods

In the following, the term "Valid" is used according to the technical definition made before.

Method

Description

void ResultStoreUtils.delete(String id)

Sets the entry with this ID to inactive. If there is no such entry, the method de facto does nothing

void ResultStoreUtils.save(String id, Object value)
void ResultStoreUtils.save(String id, Object value, Date expiresAt)

  • Creates a new entry for this ID or updates an existing entry. Existing inactive entries are also updated.

    id: Professional ID of the entry
    value: Must be of type String, Number, Datetime or Boolean and is written to the corresponding field. If the type is not supported, a meaningful error message will be thrown. "null" is explicitly not supported as a value to be stored
    expiresAt: optional, date of validity. With "null" the dataset is always valid.

  • String values are always written into the memo field. For short texts this is oversized, for JSon structures it is helpful. Limiting yourself to one field brings simplicity in use.

Serializable ResultStoreUtils.get(String id)

  • Returns the filled value (Text, Date, Number, Boolean) for the "ID" entry, if it exists and is valid.

  • If no entry with this ID exists or if it is no longer valid or inactive, the method returns null.

  • The method returns the correct data type for the filled field, i.e. if the "NumberValue" field is filled, a Double is returned, if "BooleanValue" is filled, Boolean is returned, and so on.

    • Double wert = ResultStoreUtils.get("de.cursor.churnscore.average");

Provision of a default rule for the deletion run

  • To support the cyclic cleanup of invalid entries, a default rule for the cleansing run is created. The search behind it looks for all entries in the entity "cache", which

    • are inactive or

    • whose "Valid until" date is filled and is in the past.

  • The rule is not activated in the delivery standard.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.