Customizing FAQ

General

What is Python?

object oriented

aspect oriented

functional

Why Python?

Where can I find a description of the Python functions provided by PLANTA?

The functions are described in the Python API.

What is a DTP?

DTP means Data Table Pool. Here, the PLANTA software stores all records loaded from the database (e.g. for each module search or with the Python functions: search_record, get_children etc.). There, the records are kept ready for display in one or several modules.

What is an MTS record?

• MTS records are module records, i.e., the records that are displayed in the module.
• Exactly one DTP record belongs to each MTS record.
• Example: A project including all of its fields

How is the I-number for an I-text generated?

PLANTA generates a new I-number for an I-text on the basis of an entry in the schema specific counter value table.

Depending on the license and the I-number DI, the value of the counter value 1 DI is read and used for a new I-text.

• Example for Q2B
  • Counter value table: DT 396 Counter Value Q2B
    License data item: DI 008150 License = Customer License
    DI data item: DI 008152 DI = 000985 (I-No. DI from DT434 I-No. Q2B)
    Counter value data item: DI 008164 Counter value 1

Has anything changed in I-texts compared to releases < 39?

In PLANTA project, I-texts are only stored in the schema specific I-text table.

The I-numbers table is no longer maintained or filled.

Why is no automatic number created?

Note

Settings

How do I set up the PLANTA e-mail function (in order to directly send e-mails)?

How can I change the system title?

Note

• Alternatively, it can also be set to the runtime of the system title via the following Python function:

 ui_set_system_title(title: string) 

Tip

• In order to distinguish different sessions, the currently logged-on user and the PID can be displayed in the system title.
  • If the MOD0099QC default user menu is used,
    • open the Python Macros module and change the CHANGE_TITLE variable in the on_load method from CHANGE_TITLE=FALSE to CHANGE_TITLE=TRUE
  • If an individual user menu is used,
    • open the Python Macros module and insert the following line in the on_load method of the user menu:
    • The following lines must, like the other lines, be indented by four spaces each in the on_load method.

PID = str(os.getpid())
ppms.ui_set_system_title('system title' + ', PID: ' + PID + " - " + ppms.uvar_get("@1"))

Details

• When you launch PLANTA project for the next time, the PID is displayed in the system title.
  • The PID is part of the log file as well, so all log files can always be ascribed to the corresponding session.

How can I change the editor used to edit macros, value ranges, etc.?

How can I store/use my own product logo (brand logo) throughout the system?

• In order to store an individual product logo,
  • create a new OLE object for the product logo OLEs.
  • For the required module in the Other Module Parameters module, enter the ID of the newly created OLE object in the Product logo field.
• In order to exchange the logo in the default print areas headline (header)
  • open the data area with Positioning = 3 (Print area: headline) of the module which is stored in the Skin of the current user in the Module for print area data field.
  • substitute the ID of the OLE object with that of the newly created one.
• The logo in individual print areas may have to be substituted the exact same way.
• In order to use your own product logo throughout the system:
  • create a new OLE object for the product logo and assign it to the Product logos category.
  • Switch to the Product Logos module variant.
  • For the newly created OLE object, click on the Use as logo throughout the system button.

Questions on the behavior ("Why?")

Why is a DI not displayed in a module?

Why is a newly customized context menu not displayed?

In what way are the field width, indent, and window 1, 2 and 3 width constants related?

• The values for DF width and indent are specified in tenth millimeters of the same unit.
• The specification in Width W1 etc. is no size but only serves to calculate the window's share of the total screen width.
  • Since the widths of screens (and thus the „width available“ for the panel) differ, this is no fixed value.

What are implicit fetch exits?

Why are fields not displayed in a new window?

• Upon creation of a new module in the Modules module, a width for window 1 is defined in Width W1. Hence, no explicit width must be allocated here.

Note

• If the Width Fx field (Width W1, Width W2, Width W3) is filled but no data field in the module has Window = x, window x is displayed empty regardless.

Why are entered and saved values not displayed below the scale after reloading?

Why can a newly created DI not be used/Why do changes made to the DI not take effect?

• The only exception are changes made to
  • I-texts, e.g. the DI name or
  • value ranges (including VR type)
• Meta data of the Data Dictionary is contained in the target directory. The POJO classes are not generated anew by restarting the PLANTA service. The target directory must be deleted in order for the POJO classes to be generated anew when restarting for the next time.

I cannot select any value from the listbox. Why is that?

Tip

• Via the LB: Part string search parameter, you can define which data fields of the listbox are browsed in the part string input.

Why can't I click on any fields in the form editor although customizing mode is activated?

• The data area in which the fields are located
  • has not yet been activated by clicking on it (the data area is still displayed in green) or
  • is no form (Layout = 0 or 1). The data area is displayed in gray.
    • Tip By right-clicking into an area and selecting the corresponding entry, the layout can be changed.

Why are alternating shadings displayed in black?

• In order to change this, switch to the Layout module variant in the Data Areas module and select the required value for the Altern. Color W1 DI (Altern. Color W2 or Altern. Color W3) from the listbox.

Why does a filter criterion not apply in recursive structures as it is expected to?

Why does a filter criterion not take effect?

Why are the charts not displayed in a copied module?

• In the chart data field in the da_id=" parameter in the Data field configuration field, you can define which data area the data for the chart stem from.

Example

"""Define Chart - Properties"""
da_id='045968'

• If a module is copied, the data area IDs change. Therefore, the data area ID of the source module must be replaced by that of the new one.

Tip

• The easiest way to find out which data area ID must be used, is to look up which data area was used in the source module and which data area of the copied module equates to it.

Why can a file which was copied from the template not be opened in a hyperlink field?

Perhaps the template path stored in the customizing is not correct. This path is stored in the sub-DI with CR function.

Why is the new version of a changed variable no longer displayed in the system after the client was restarted?

• In PLANTA project 39, variables behave just like in the previous releases (like e.g. 3.7 and 3.8).
  • This means that they are loaded to the main storage when the session is started, provided that they are not directly changed in the database, their values apply only to the current session.
  • Hence, by increasing a variable via Python macro, only the value in the main storage is changed, not the one saved in the database.
  • After closing the session and restarting, the value in the main storage expires and the value from the database is fetched again.
  • The same applies if a second session is opened simultaneously. Here, the value saved in the database is read in as well.

Why can a file which was copied from the template not be opened in a hyperlink field?

Customizing Tips ("How?")

What can I do to enhance the performance?

• If most modules are slow,
  • check whether the environment complies with the hardware requirements (specifically: main storage dimensioning, latency between database and application server and database performance (e.g. indexes)).
• If a specific module is too slow,
  • check the module construction. E.g.: are data areas or data fields contained in the module which are not required?
    • For performance reasons, only customizing objects which are actually required should be embedded in a module in general (i.e. data areas, data fields).
    • The data in data areas with Never display = are loaded as well, i.e. it is not sufficient to set a non-required data area to Never display = .
  • check the (Filter from, Filter to, Regular expression) filter criteria.
    • Are there filter criteria on real data fields or only on virtual data fields?
      • Reason: Filter criteria on real data items are evaluated in the database and filter criteria on Virtual data items are evaluated in the main storage, i.e., if filter criteria are only set to Virtual data items in a module, all data is loaded into the main storage first, in order to be restricted to the filter criteria there.
        • For virtual data fields, the value in Filter from and Filter to is marked red and bold.
      • The same applies to regular expressions.
    • Most value ranges and fetch exits can be converted to a Python value range with the computeSqlValueRange() function. Fields with such value ranges are known to the database. That is why on such fields, filter criteria do not only take effect in the main storage but on the data base.
  • check whether numerous implicit fetch exits are used in this module.
    • For performance reasons, implicit fetch exits should not be used in modules with large amount of data.
  • check whether value ranges are used in this module in which the DtpRecord.get_children() Python method is used without specifying a DI list.
• If a panel loads slowly or the loading of the tabs stagnates for certain submodules,
  • check the Python macros of the submodules
• If a particular customized function is slow,
  • check whether the macro of this function initiates the reloading of submodules that have not been loaded completely in the current panel.
• Furthermore,
  • frequent or recurring database access via customizing, e.g. by setting up caches, should be avoided.
  • * should only be used as dependency in value ranges if this is necessarily required for functional or technical reasons. Reason: Value ranges with * dependency are recalculated upon every action in the system, i.e. also if another module is opened for instance.

How do I have to specify paths in the client_exec() Python function?

• Variant 1:

ppms.client_exec("""
env = get_Env()
mod = env.ActivePanel.ModuleManager.__getitem__('%s')
doc = mod.CreateExcelExportDocument(fullExportPath = 'C:\\\\Directory\\\\Subdirectory\\\\filename')
env.GenerateExcelFile(doc)
""" % uid)

• Variant 2:

ppms.client_exec(r"""
env = get_Env()
mod = env.ActivePanel.ModuleManager.__getitem__('%s')
doc = mod.CreateExcelExportDocument(fullExportPath = 'C:\\Directory\\Subdirectory\\filename')
env.GenerateExcelFile(doc)
""" % uid)

• Variant 3:

ppms.client_exec("""
import os

env = get_Env()
mod = env.ActivePanel.ModuleManager.__getitem__('%s')
doc = mod.CreateExcelExportDocument(fullExportPath = os.path.normpath('C:/Directory/Subdirectory/filename'))
env.GenerateExcelFile(doc)
""" % uid)

Notes

• The specification of the file ending is optional.
• If the file name is specified without any path, the file is stored in the My Documents folder (%USERPROFILE%\My Documents).

See also: IronPython API, Python API, Python documentation to \ (backslashes)

How are the currency formats customized by default?

How is the height and width of listboxes adjusted?

• The height (or width) of listboxes must not be adjusted manually but is calculated on the basis of the number of values (or width of the fields).
• There is a minimum and a maximum height or width.

How can line breaks be adjusted in a data field?

How can I customize a frame (a blue one in the standard) for a listbox?

Note

• The blue color in the standard has the symbol ID 001975.

How can the content of the current @L-variable (list variable) be displayed?

How can the content of a specific variable be displayed?

How can the alignment of the data field content be changed?

How can I enhance the performance of the resource structure customizing?

How can I customize a newly opened submodule as a tab behind the main module?

The dock_to_module parameter in the open_module() method must be set to the value as the UID of the module to which the submodule is to be docked.

Example

mod_obj = ppms.get_target_module()
mod_obj.open_module('ID of the module',forced_status=2,dock_to_module=mod_obj.get_uid(),dock_style=0,foreground=0,focus=0) 

• Explanation:
  • mod_obj is the main module to which the submodule is to be docked.

How can I read a record from the DTP or fetch it from the database to the pool?

Parameter

• dt_num: ID of the data table
• key_list: List of the Python IDs of the 1:1 key of the data table
  • In compound keys, all DIs (same order as in the data table) must be specified.
• di_list: List with all DI-IDs (without leading zero) to be contained in the DTP
  • Here, all DIs that are accessed in the further calculation are to be specified.
• dblookup: Specifies whether the value is to be read from the database, in case the record does not exist in the pool.

Notes

• The di_list list must contain at least one DI.
• 1:1 keys and foreign keys are loaded into the DTP automatically, even if they are not contained in the di_list list.

Examples

• Example 1

pr_id = ?4711?

rec461=ppms.search_record(461, [pr_id], [1052,1062], True)

• Explanation:
  • The rec461 variable now contains a DTP record with the following DIs (in addition to the primary and foreign keys of DT461)
    • 001052 Main Project ID
    • 001062 Manager

• Example 2

pr_id = ?4711?
task_id = ?2010?
res_id = ?R1?

rec466=ppms.search_record(466, [pr_id,task_id,res_id], [1510], True) 

• Explanation:
  • The rec466 variable now contains a DTP record with DI 001510 Actual load (in addition to the primary and foreign keys of DT466).

How can I have two (or more) data fields displayed behind a bar?

• enter the Python ID of the bar data field for both data fields in the Bar link (DF Python ID) parameter,
• define the position of the auxiliary bar field in the Dock point parameter, e.g. 1 Start point is bar end.
• X-pos of the 2nd data field = x-pos of the 1st data field = DF width of the 1st data field + 1

How can I have a data field displayed without heading?

• If the data area has a horizontal layout (Layout parameter = 0) or a vertical layout (Layout = 1),
  • enter a protected space (Alt + 160) in the DF heading parameter in the Data Areas module for the data field the heading of which you do not want to have displayed.
• If the data area is a form (Layout = 2), you can hide the heading
  • by activating the customizing mode menu item in the module by clicking on the heading and pressing DEL or
  • by deleting the X/Y positions of the heading in the Layout module variant in the Data Areas module.

Customizing In Two Sessions

CTRL + F3 For Opening the current data area/F9 for opening the module

From DB 39.5.0

Only users NEW with Customizer rights = can

• open the customizing of the current module in the Modules module by pressing F9
• open the focused data area in the Data Areas module by pressing CTRL + F3

Note

• It is no longer sufficient to only have access to customizer menu items in order to access the customizing modules mentioned above.

Up to DB 39.5.0

Users to which the customizer menu items are assigned can

• open the customizing of the current module in the Modules module by pressing F9
• open the focused data area in the Data Areas module by pressing CTRL + F3

Automatic Creation of Incarnations

Convert Round Value Ranges to =computeSqlValueRange() value ranges for Performance Reasons

Example old

(ROUND(DI001510,2) != 0.00) ||
(ROUND(DI002669,2) != 0.00) ||
(ROUND(DI002671,2) != 0.00)

Example new

def computeSqlValueRange(dt_name):
    val = """case  
                when nvl(DI001510,0)+nvl(DI002669,0)+nvl(DI002671,0) > 0 then 1
                when nvl(DI001510,0)+nvl(DI002669,0)+nvl(DI002671,0) = 0 then 0
            end"""
    return str(val)

Python: How can I add elements to a list?

• Variant 1

value_list = [["R1"],["R2"],["R3"]]
f_list = []
i = 0
for rec in value_list:
    f_list.append(value_list[i][0])
    i = i + 1

• Variant 1 (structured)

value_list = [["R1"],["R2"],["R3"]]
f_list = []
for rec in value_list:
    f_list.append(value_list[0])

• Variant 1 (one-liner)

value_list = [["R1"],["R2"],["R3"]]
f_list = [rec[0] for rec in value_list]

How can I expand the _Copy Schedule function?

Example: Additionally, the todo item notes are to be copied.

• Create a data area from DT805 Todo Item Notes.
  • Tip: copy the corresponding data area from the schedule (0099AN in the standard).
• Allocate a DA Python ID (e.g. open_item_notices_area).
• Embed the data area in the Copy schedule (0099J9) module.

Note

• Only values from input data fields (data field behavior, e.g., i, i2 or li) are copied.

How can I have the Σ sigma sign displayed?

Customize the symbol with "Font" = "Symbol", store it on the required field or heading and write S in it.

How can I embed an individual user menu?

The User Menu module can be copied and adjusted individually. The copy of the user menu can be stored in the Skins module in the skin of the users in the User Menu field.

How can the splash screen be exchanged?

• Replace the splash.png file under %client_folder%/Resources/ with the provided file.

See also: Splash Screen, use product or company logos

How can texts in e-mails; e.g. signatures, be changed?

Procedure

• Customizer Module Customizer Open the Modules module
• Insert the module ID 009A3F
• Open the DA041375 Stakeholder data area.
• Expand the tree structure of DI026625 E-mail
• In the subject_text and body_text parameters in the Data field configuration, texts to be inserted automatically can be stored for subject and e-mail content.

Messages

What does the IE: (MV creation/application/saving) "[Module variant ID]" uses these unsupported DIs: DI [Data item ID] message mean?

Upon customizing of a Python value range, an error message is displayed. What does it mean?

Examples of error messages

• IE: "deps" attribute of computeOutput() function in VR code of DI [Data item ID] must be a tuple. The function won't be available.
  • Meaning: In the dependency, a tuple must be specified. I.e., if you want the function to have only one dependency, this is specified as follows: deps = ('DI [Data Item ID]). Further Information on dependencies
• IE: processInput() function must take exactly 2 arguments (DataItem reference and old DI value), but in VR code of DI [data item ID] it takes 1 argument(s) and thus won't be available.
  • Meaning: The processinput() function requires two transfer values (di, oldvalue). Further Information on Python value range functions

Note

• Further information on error messages in Python value ranges

What does the Python error in the [macro ID] macro. Class 'SyntaxError': ("Non-UTF-8 code starting with...) error message mean?

• Forbidden characters must not be used in comments on the Python code either.

Why is the Scale assignment not possible: MOD [Module ID], DA [data area ID], horizontal bar DF [data field ID] (DI [data item ID]) message displayed when a module is started?

This message is displayed if no scale area is assigned to a module, or the DA class parameter is unequal 1 (scale area).

Map Functions from Releases 3.8 in PLANTA project