Skip to content

Configuration Best Practices

Configuration is one of the ways in which a customer solution can be tailored. Configuration can be used on its own, or in combination with extending on the outside or extending on the inside.

Before deciding to implement a certain tailoring requirement using configuration, make sure you are familiar with the guidance for choosing the right type and level of tailoring as well as the key principles when combining tailoring types.

Custom Objects Lifecycle Management

Management of Custom Objects

Custom Objects might be created by the customer, by IFS or by Partners. It is recommended to attach Custom Objects to an Application Configuration Package (ACP) and put the ACP into the solution repository in the Build Place. As a result of this it will be possible to analyze impacts when updates are applied.

For more information on this, read about Configuration Management

Interaction between Customization and Configuration

We should not develop a customization on top of a configuration. This means, for example, that customizations should not read data from or write data to custom attributes or custom entities. A customization should not make any use of Custom Enumerations.

This means that everything required by the customization should itself be in the customization layer i.e. fields should be a part of this customization (or another customization).

This guideline arises from the fact that development and delivery are generally linear, so e.g. it is reasonable to build customization B on top of customization A.

However we cannot assume that a configuration item both exists and is published, in a particular environment, and if it is not published then the customization may not deploy or compile correctly. The configuration item might also be subsequently changed by an administrator, causing invalidity in the customization at a later date.

Delivery Sequence Considerations

Custom Objects are highly dependent on the state of the environment in which they were developed. If a customization is present (delivered and deployed) in Sandbox but not in PreProd, a configuration created in Sandbox that uses fields from the customization would not be able to be deployed into PreProd (yet).

Configurations may be impacted, and might stop working, if they were developed against an initial delivery of a customization but then the customization was substantially reworked, and fields were removed or changed.

Configuration Specifications

When a Consultant or Customer BA is designing a configuration to be developed by another party, it is recommended to use the template document in the IFS Value Services Portfolio > CRIM Specifications > Configuration Specification Template.

This is a different template to the Functional Specification (intended for Development specifications).

Entity Configurations

What are Custom Attributes?

In IFS Cloud we can add:

  • Custom Attributes on a Standard Entity (known as Custom Fields in IFS Apps 10)
  • Custom Attributes on a Custom Entity (known as a Custom Logical Unit in IFS Apps 10)

A persistent attribute is a way to store a useful data element on an object.

A read-only attribute is used to fetch and display a value from another table.

A read-only attribute is useful to provide a quick calculation using IFS data e.g. the average number of hours to perform a certain type of task.

Best Practices for Custom Attributes

There is no specific upper limit on the number of fields that can be added to a logical unit, but occasionally we see performance issues when more than 15-20 custom attributes are added to a page. This can sometimes be mitigated by investigating the fields to make them more efficient.

When creating a Persistent field that should act as a yes/no slider, it is recommended to use the standard Enumeration called FndBoolean.

When creating Read-only fields, type Reference is usually the most efficient; and therefore preferred to SQL Statement and Expression. However, SQL Statement and Expression are much more powerful for the fetching of complex data.

Read-only fields that perform full table searches or call many API methods can have a significant impact on performance, so they should be built carefully to maximize efficiency. Poor page performance sometimes turns out to be caused by a custom attribute that takes many seconds to evaluate.

There are scenarios where a read-only attribute can suddenly cause errors on a page, after publishing. One example is where we join tables that have the same data but in different datatypes, such as where a work order number is stored as VARCHAR2. If we call a work order method but pass in text, the end user will get an “invalid number” error.

Best Practices for Custom Entities

Custom Entities (custom logical units) are intended as a way to create a simple table of objects, similar to a basic data table in standard IFS.

They do not handle multi-level e.g. parent-child-grandchild data structures very well, because they do not have truly user-defined key columns, but instead rely on the unique ROWKEY column. Alternate Keys can be defined but they exist only in the metadata (so they do not enforce restrictions at the oracle table level), and null is accepted as a value in alternate-key columns. For complex data structures it may be better to recommend a customization.

Custom Enumerations

What are Custom Enumerations?

Custom Enumerations are used to define a list of options, typically to be used in a custom attribute.

A similar result can be achieved using a Persistent, Reference-type custom attribute (which means it allows you to reference a record in another logical unit).

How to choose between these 2 approaches?

  • If the user needs to be able to select multiple options, a Custom Enumeration should be used.
  • If it is important that new options can be added by super-users (similar to adding basic data) then Reference field might be preferred, because editing a Custom Enumeration is an administrator activity.
  • If a very large amount of options is to be defined, then Reference field should be used since there is a limitation on the overall storage capacity of a Custom Enumeration.

Custom Events

What are Custom Events?

Custom Events are triggered when an IFS database object is added, modified or deleted.

Custom Event Actions have several action types, such as Send Email. These types generally have a low impact on the solution.

A larger impact may be seen with event actions of type Execute Online SQL. These allow skilled consultants to develop PL/SQL scripts that perform validations and either display conditional messages to the user (such as an error message that rolls the transaction back), or perform new, modify or remove transactions on IFS business objects.

These event actions are sometimes used to define custom Business Logic relating to customer-specific custom fields etc.

Execute Online SQL Event Actions - Benefits

These event actions:

  • Can be developed in a fast and flexible manner; so it is easy to make a small adjustment to the script without going through a lengthy redesign, rework and delivery process
  • If written well and documented well, then the risk of issues down the road is suitably mitigated

Execute Online SQL Event Actions - Concerns

In many projects we see PL/SQL event actions that are very complex, poorly documented and difficult to maintain:

… when event A happens, create order B with lines C, D and E, connect documents F and G, link it to project H and then release it…

These event actions are not supported by IFS Support, and it may be difficult to identify the creator, who might be the only person who truly understands what the event is doing. Sometimes an issue will spend days in Support before it is found to be caused by a custom event, meaning significant cost.

If the event makes database queries, its performance may degrade over time due to the steady expansion of data in tables – but it is hard to foresee that problem during the implementation when only a small amount of data exists.

Another performance issue is that the custom event creates a PL/SQL block that is executed which contains data in clear text. For example it shows part number 1234 and site X. That has the downside that the SQL has to be parsed each time. It also makes it hard, even impossible, to find the event code in Oracle Statspack reports since the total time of an SQL statement is not aggregated.

It is important to note that IFS intends to remove the Execute Online SQL event concept in a future update.

Best Practices for Custom Event PL/SQL Actions

A few tips on good custom event development practice to reduce risk:

  • Document the objectives, use cases etc. clearly in the event action description, code comments, and in documents that the customer possesses e.g. Scope Tool outputs.
  • Use a proper code developer such as PL/SQL Developer. The Custom Event Action script field allows bad characters such as curly quotes and hidden whitespace.
  • Use standard IFS API methods such as New__, Release__
  • Avoid straight DML commands ( INSERT INTO… etc.)
  • Use Client_Sys.Add_To_Attr and similar standard formatting APIs.
  • Avoid formats like: Variable_ := 'column'||chr(31)||'value'||chr(30);

  • Use Explicit cursors when needing to find existing data. These look like: CURSOR get_row IS select …

  • Avoid Implicit cursors, because they can lead to the “no data found” error which is hard to debug. An implicit cursor looks like this: Select a, b, c into a_, b_, c_ from …

  • Use good code generally. Using well-known PL/SQL syntax is a good idea, so that consultants and support can interpret what the intent was.

  • Do not include Commit statement.
  • If the event action is designed to do some analysis and then conditionally display a message to the user, it’s a good idea to include “Custom Event {Name} …” in the error message so it is obvious where it is coming from.

  • If introducing a PL/SQL event action into a critical business process - such as receiving a shop order product - we want to avoid the risk that any issues with the event prevent that process from proceeding (could be a major business impact). In this case it might be wise to execute the complex logic as a background job. This way, the worst that can happen is that the background job fails. The background jobs should be monitored for failures.

  • Another benefit of using a background job in this way is that we can provide unlimited progress information in the background job details. If done well, this can make it much easier to debug any failures using the information captured in those “logs”.

  • If trying to update a record in the same table as the one that triggered the event, a background job has to be used to avoid the “mutating table” error.

  • Anytime data is being written into another table, be mindful of field character lengths. The target column may accept fewer characters than the source column.

  • Consider using configuration tables that reduce the need to hardcode basic data values into the event action. A likely cause of a fault is when someone tries to retrospectively add a basic data value to a list defined within the event action, but inadvertently removes a bracket or semicolon. A better solution is to add a yes/no attribute to the basic data table so that rows can be marked as included in the event (this way the user is updating data rather than code). If there is a need for a more arbitrary configuration table that does not map easily onto a standard basic data page, a Custom Logical Unit can be used to create a rudimentary configuration table.

Aurena Projection Configurations

What is Aurena Projection Configuration?

Projection configuration is a capability within Aurena that allows us to extend the functionality of a projection, which is basically a webservice. We can do two things with Projection Configuration:

  • Add entities to the Projection (i.e. expose additional data and resources)
  • Enable custom actions (specific API methods). Within the Aurena UI, these would then be used to create custom commands (user buttons) via Aurena Page Designer. Outside of Aurena UI, Apps could be developed that made use of these actions

Best Practices for Projection Configuration

For Entity Associations:

  • Try to use an Association Name that clearly indicates the parent/child relationship of the association.

For Custom Actions:

  • Note that the same custom action can be called by multiple custom commands in page designer, passing differing sets of parameters. Therefore, the Action Name defined here should generically indicate the PL/SQL method that it exposes; not necessarily how it is going to be used in a custom command.

Aurena Page Designer

What is Aurena Page Designer?

Aurena Page Designer is an a Aurena Super-user tool that allows us to change the sequence of fields, hide fields, add fields, add objects, change labels, change field behavior etc. It also allows creation of custom commands (buttons) in Aurena pages. However there are limitations - it does not allow us to do everything that can be done in Aurena Client Development.

Best Practices for Page Designer

Use contexts when designing pages. Contexts are intended to enable different versions of a page to be defined for different sets of users within an IFS environment – sets defined by default company, user group etc.

When not working in any specifically-defined context, you are in the Global context. It is a good idea to keep the Global context vanilla (i.e. unconfigured). If you type “scope=999” (where 999 is not a scope that actually exists) into the URL you will get to view the global context. Having the Global context unconfigured makes it easy to "sanity-check" new customization deliveries.

When a customization adds some features to a page, they may not be shown to the user because page configurations have been performed. This is because Aurena cannot merge the customization content into a configured page design, and it prioritizes page designs over the customization content. The best way to get the customization to show through in this scenario is to revoke, and if necessary redo, the page designs. It is only necessary to revoke the page designs on the artifacts affected by the customization; not necessarily the whole page. Nevertheless, this can be annoying if a lot of page design has been done.

It is hard to keep track of all the different page designs, versions, and people doing page design within a project because the page design is stored as a table of metadata XML files, not as individual tangible database objects – and there is no built-in version control. To mitigate this it is wise to have either a best page design environment, from which designs are rolled out to other environments, or a best page design context – which separates “finalized” page design from page designs in development. If it is clear that a particular piece of page design work is not going to be kept, try to remove it (returning the page to the default layout) in order to avoid confusion.

Page Designer – Custom Commands

Custom Commands allow us to create buttons that perform a navigation, launch a quick report or execute a PL/SQL method. This can be a standard IFS method or a method in a package added by Customization.

Application Configuration Packages

What is an Application Configuration Package?

Application Configuration Packages (ACPs) provide a system to manage, export and import configurations (custom objects). An ACP can be thought of as a folder within IFS to which we can attach custom objects such as Custom Attributes, Custom Enumerations and Aurena Page Designs.

It is important to understand that the ACP is just a set of pointers to custom objects. It is not a snapshot of what the custom objects were at some point in time. However, when we export the ACP to file, we are exporting the custom objects as they are at that moment.

Any custom object can only be connected to one ACP at a time.

ACPs can be exported and imported by an end user account (with the necessary permissions) as opposed to the application owner account, for which most customers do not have the password. ACPs can be imported using the IFS Cloud Aurena interface.

What are the benefits?

ACP makes it very easy to export a large number of custom objects to file at the same time. It is also quick and easy to import those objects into another environment. Export can be to Zip file, or XML files and folder. The Zip file approach is cleaner in most cases (and easier/safer to send as an email attachment).

ACPs are a convenient way to track the development of custom objects over time. If we put the current date into the ACP name we can export it week after week, and thus have a way to look back at what the custom object used to be.

What are the limitations?

Consider two environments, Sandbox and Preprod. We develop custom objects W, X and Y in Sandbox, then export them via ACP and import them into Preprod. Some time later, in Sandbox, we have removed object X and added Z. We can again export the ACP and import it into Preprod. However, the result is that Preprod now contains W, X, Y and Z. This is because ACP import does not handle removal of objects that are no longer in the ACP. It only handles new and changed objects currently in the ACP. In this scenario, removal of object X from Preprod would have to be done manually.

Another important point is that the custom object pointer is based on the ROWKEY, not the object name. If we independently create the “same” custom object in two environments, they will have differing ROWKEYs. If we try to export one and import it into the other environment, we will receive a conflict; basically the issue is that “another object already exists with that name but a different ROWKEY”.

Best Practices for ACPs

It’s a good idea to put all custom objects into an ACP. This provides overall organization, and helps to ensure no custom objects get “left behind”.

One suggestion is to create an ACP per block of functionality – perhaps encapsulating some custom fields, and custom events that are linked together to solve a particular gap. This can lead to a large number of ACPs over the course of a project. Once the custom objects are stable it might make sense to consolidate into a few, larger ACPs – but in practice this will require coordination between the people who developed them.

Prefix the ACP Name with “IFS”, or the Partner Name (if it was created by one of those parties), or the name of the consultant/user who created the objects for easy tracing.

It is recommended to check the ACP into the Solution Repository so that Impact analysis of updates can be performed.

Aurena Configurations, such as Projection Configurations or Aurena Page Designs can be attached to an ACP. It’s usually best to keep these in a dedicated ACP separate from ACPs that contain custom fields etc.

There is a deployment sequence in some cases – for example if we have a custom enumeration, a custom persistent field and a custom read-only field that are all related – then they would have to be published in that sequence. If they are in the same ACP, this will probably mean that they need to be published one-by-one.

Custom Utility Packages and Views - Guidance

Customization and Configuration Guidance

There is a clear separation between the Customization layer and the Configuration layer. This is important for several reasons, but chiefly because deployment issues are likely to occur if Customizations are built on top of Configurations, that is to say, if a custom object in the Configuration layer is a prerequisite for code in the Customization layer.

The simplest and most likely example of this would be a Customization that reads (or sets) the value of a Custom Attribute. Equally, a Customization in IFS must not use a Custom Enumeration, Custom Entity or Custom Event.

(Note that it is common and perfectly acceptable to build Configurations on top of Customizations).

While there is not yet a barrier in IFS Cloud that prevents Customizations being built on top of Configurations, this is likely to be added in a future update.

What are Custom Utility Packages and Views?

IFS Developer Studio allows the creation of Utility models. These can be thought of as pieces of code that do not tie to a particular database table. They are generally used to provide supporting functionality and methods in a particular area. Utility models can be used to create database packages and views.

How have Custom Utility Packages and Views been used?

Some IFS customers have made use of Utility Packages and Views to create lightweight customizations that manipulate the values of Custom Attributes. A typical usage has been to define a Custom Event or Custom Command (previously a Custom Menu in IFS Enterprise Explorer) with some embedded PL/SQL code that calls a method in a Custom Utility Package; and that method performs a series of actions, reading, inserting and modifying data, including Custom Attributes.

While the Custom Utility Package would generally be developed “informally” i.e. by a consultant or super-user and without detailed specification, it has to be considered a Customization because it introduces code changes.

Similarly some IFS customers have implemented custom views using Developer Studio/Utility models.

The appeal of this usage was:

  • The ability to use Custom Attributes in the Customization
  • The rapid and flexible implementation and delivery

The problem with this usage is:

  • It contravenes the rule that Customizations must not be built on top of Configurations (because the Custom Attributes – Configuration layer – are a prerequisite for the Custom Package - Customization layer).

What are the intentions of IFS in this area?

IFS intends to deprecate the ability to use PL/SQL code blocks via Configurations, in order to make the product more supportable. This means that Custom Events Actions with Execute Online SQL will be deprecated.

In the future it may not be possible to deploy a Customization that depends on Configurations.

BPA Workflows

In IFS Cloud, Custom Events with Execute Online SQL will be deprecated in a future update. The replacement is the BPA Workflow functionality. BPA Workflows exist in the Configuration layer and therefore we can use them to read and manipulate both standard attributes and Custom Attributes, without contravening the layering rule. BPA Workflows are recommended for requirements such as

  • Updating fields/creating records based on a database event
  • Notifying the user via warning and error messages

Query Designer

IFS Cloud Query Designer is the tool to use for development of new data sources for functionalities such as Page Configurations and Integrations.

Query Designer is a tool in the Configuration layer and therefore it can be used to query standard and Custom Attributes without breaking the layering rule.

Customization (Extending on the Inside)

When the requirement is very complex, the recommendation remains to do a formal Customization of IFS. This means following the standard Customization process, developing, testing and delivering code. The delivered code will be uploaded to the Customer’s Solution Repository.

It is important to note that such a Customization must not use (read/create/update) data from Custom Attributes. This means that all of the non-standard attributes required by the Customization must also be a part of the customization (or of a prior customization).