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.
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 Events¶
What are Custom Events?¶
Custom Events can be triggered when an IFS database object is added, modified or deleted.
Custom Event Actions can be created with several action types, such as Send Email and Streams. These action types are recommended for notifications since they generally have a low impact on the solution.
Another Custom Event Action Type is Execute Online SQL. These actions have been used by some customers to create very complex embedded PL/SQL code to achieve automations, and make updates to IFS data tables. This has led to problems with
- ability of IFS to support the solution
- impacts on the update process
- unforeseen performance impacts
- ability for the customer to be Evergreen
Best Practices for Custom Events¶
Custom Events are a key part of the IFS solution for many customers.
The action types Send Email, Streams and Tasks provide easily configured solutions for notification-type requirements.
The action types REST Call and Application Message enable some more advanced capabilities for administrators.
The action type Workflow allows us to call BPA workflows that handle data enrichment, validation etc. This is the main replacement for the Execute Online SQL action type.
IFS recommends that the Execute Online SQL action type is NOT used, going forward. The recommendation is to use BPA Workflows to solve more advanced requirements.
Note that IFS intends to remove the Execute Online SQL event action type in a future update.
For those customers that have used Execute Online SQL event actions in their existing solution, IFS now recommends the phasing out (replacement) of these elements, during or after the process of upgrading to the latest version of IFS Cloud. This will require analysis to determine which can be replaced using another approach such as a Workflow, Extend on the Outside or Extend on the Inside; and which can be removed, perhaps because new features in IFS Cloud render them redundant.
Please also read about Custom Utility Packages and Views, which is closely linked to the Execute Online SQL action type; there are more details in that section on the alternatives recommended by IFS.
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 code that does 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.
Issues caused by the use of Custom Utility Packages with Configuration Objects¶
Some IFS customers have used Utility Packages and Views to create customizations with the goal of manipulating the values of Custom Attributes. A typical usage was to define a Custom Event (or Custom Command, previously a Custom Menu in IFS Enterprise Explorer) with some embedded PL/SQL code that called a method in the Custom Utility Package; and that method performed a series of actions, reading, inserting and modifying data, including Custom Attributes.
The Custom Utility Package would often be developed “informally” i.e. by a consultant or super-user and without detailed specification and hence was sometimes incorrectly thought of as Configuration. This kind of development is a Customization because it changes the codeline.
Likewise, some IFS customers have used Developer Studio utility models to implement custom views that include (are dependent upon) custom attributes or custom entities.
The problem with these usages is that they break the layering rule, because they create Customizations that are dependent on Configurations.
This approach will likely lead to difficulties in the deployment of updates, problems with Support, and generally make it harder for the Customer to have an Evergreen experience with IFS.
To be clear: there is nothing wrong with developing Utility packages (or views) in Developer Studio following the proper development processes. The problem is when the Utility package is made dependent on Configuration objects (including Custom Attributes, Custom Enumerations and Custom Events).
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 the Execute Online SQL custom event action type will be deprecated.
In the future IFS may also make it impossible to deploy a Customization that is dependent upon Configurations.
Advice for Upgrading and New IFS Customers¶
For upgrading customers that have used Custom Utility Packages in this way in their existing solution, IFS now recommends the phasing out (replacement) of these elements, during or after the process of upgrading to the latest version of IFS Cloud. This will require analysis to determine which can be replaced using another approach such as a Workflow, Extend on the Outside or Extend on the Inside; and which can be removed, perhaps because new features in IFS Cloud render them redundant. Some of the options are summarized below.
For customers performing new implementations, IFS strongly recommends not using Execute Online SQL event actions or Custom Utility Packages that are dependent on configurations. The alternatives below are recommended instead.
BPA Workflows
In IFS Cloud, the Execute Online SQL custom event action type will be deprecated in a future update. The replacement is the BPA Workflow functionality. BPA Workflows exist in the Configuration layer, so we can use them to read and manipulate both standard attributes and Custom Attributes, without contravening the layering rule.
In fact, BPA Workflow capabilities surpass what could be achieved with Execute Online SQL event actions in several ways.
BPA Workflows are the recommended approach for requirements such as
- Data Enrichment i.e. updating fields/creating data records based on a database event or projection action
- Data Validation, and notifications to the user via warning and error messages
- User Interaction, gathering additional inputs from the user via dialog windows
Query Designer
IFS Cloud Query Designer is the tool to use for development of new data sources for functionalities such as
- Page Configurations
- Lobbies
- 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).