Creating application logs for your processes

[Reinier]

Creating application logs for your processes

When developing processes, especially background processes, you want to keep track of the progress of your process. For small processes, this can be achieved with error handling. For larger processes, you might want to add application logs to save some information about the current status of your process.

Skip to “How to create an application log”

What is an application log

Application logs are records of the applicationlogs table, used in almost all components to write a message about the current status of a process. These logs are grouped in a data source, have a message and have a type. Usually, they also have a record reference.

You can consume the concept N_ApplicationLog, and the features N_Log data source (which comes with the concept N_LogDataSource), N_Log message (string) and N_Log type (which comes with the enumeration N_Applicatielogniveau) to start creating application logs.

Application logs in the Concept manager

What is a data source

The data source of an application log allows for:

• Categorizing your logs per business domain or process
• Subscribing to data sources and receiving mails when logs are added

It is a record in the datasources table, and is required to exist before you can add an application log. Usually, one data source exists per component and is distinguished by a component-specific check box.

In Novulo Kassa, the concept N_LogDataSource is expanded with the check box “Is for point of sale”, allowing Novulo Kassa to ensure the existence of a data source where is_for_point_of_sale.equals(yesno:load(1)). All application logs from Novulo Kassa are created with this data source

What is a log type

The log types of application logs define the urgency of an application log. This enumeration consists of “Critical error” (most urgent), “Error”, “Warning”, “Information” and “Verbose” (least urgent). When subscribing to a data source, you can specify which urgency you want to receive e-mails about.

• Critical error: this error causes full non-availability of the application. (very rare)
• Error: an error occurred during the process. It could stop the full process, or only affect a specific part of the process. It does require attention.
  1. Example: a mail cannot be sent as the e-mail address is invalid.
• Warning: something happens that requires attention, but the process has not been interrupted.
  1. Example: an automated process finishes, but take longer than expected.
  2. Example: a user explicitly chooses to ignore a warning message
• Information: to log an event that is supposed to happen
  1. Example: register the start and completion of a night run of an automated purchase generation process
• Verbose: to log extensive information from activities
  1. Example: all suppliers and products that are purchased in an automated night run

The application log type enumeration in the Concept manager, added automatically when N_Log type is added to N_ApplicationLog

What is a record reference

Usually an application log contains a message about a specific record. For instance, if an invoice could not be finalized, you’d want to know which invoice contains the issue.

To easily find the record that your log applies to, you can set the record reference field, so the user can see, and navigate to, the relevant record.

How to create an application log

To create an application log for your process, you want to:

1. Ensure that a data source exists
2. Decide on the message for your log and an appropriate log type
3. Use the consumed process component “N_Application log - Write log with dynamic record reference”

In this example, I created a reusable process component that creates log based on a parameter sales. As you can see, I start by ensuring that a data source exists, and then write the log with the consumed process component.

Ensuring a data source

Usually, you want to have one data source for all the logging of all processes in one component; so one data source per component. “Ensuring” its existence means:

1. Use a CacheValue action to find whether the data source exists already
2. If it exists, return the found data source
3. If it doesn’t exist, add the data source

Typical lay-out of a process that ensures a data source. This process component does not have a parameter, and has the return value data_source along with the defaults success and error.

Typically, we add a component-specific check box to the data source page, so we can use that check box to ensure that our component-specific data source exists. The find action will look up the first data source where the check box equals yesno:load(1), and if it doesn’t exist, the add record action will add a data source with the check box set to yesno:load(1). Don’t forget to also fill in the name!

If you want to share a data source between multiple components, the check box, or other deciding property of the data source, has to be produced in the Reference Architecture.

On this virtual page of the concept N_LogDataSource, the check box “Unique check box for my component” is added, so the processes in this component will add logs to the Data source where this check box is checked.

Creating a log

After setting up your data source, you can decide on the details of your application log. Depending on the situation in your process, you might want to write a warning or maybe a critical error. Usually, for background processes, we write verbose logs to keep track of what the background processes have been doing.

The process “N_Application log - Write log with dynamic record reference” has 5 parameters:

• log_message with type String; enter your message here. You can create any string expression. A good example is counting how many records have been processed and displaying that in your message
• log_type with type NApplicatielogniveauSr29849; select the type for your message
• data_source with type N_LogDataSource; enter your ensured data source
• record_reference with type Mixed; enter whichever record is relevant to your application log!This can be of any record type. If your log is about a failed generation of a document, enter the N_Activity record. If your log is about a failed conversion of a sales, enter the N_Sales record, etc.
• commit with type Boolean; enter true if you want the log is complete and can be committed to the database. Enter false if you want to finish the log record yourself. In this case, the log record remains locked, so you can update more fields on it, make other changes, and then commit and unlock the record

Example of the parameters of the consumed process. Because in my example, I created the extra process layer “Sales - Write application log”, I just reuse the parameters I defined there.

[j.batzke]

Thanks for the post!

@Reinier

enter whichever record is relevant to your application log!This can be of any record type.

Can I also enter a list of records to the “record reference” parameter, or would it break?
For example [users:load(1), saleslines:load(123)]

[m.gechev]

You can enter a list of records parameter, AFAIK it won’t break simply it won’t work. The field expects an expression that resolves to a single record.

Also, better use the DataStructure_DataType + RecordLink field combination instead - it is better optimized for SQL the least. -

Link records based on expression strings

Credits to @m.gechev. Original is KB1670 Record Link Field Since revision 115202, the Expression tools plugin provides a UI element in the architect that can be used to create a link to another record in the application. This field is of numeric type and in a sense, it is an autocomplete element - just like search links. However, compared to search links, it can be configured to accept records of any type, whereas the search link can contain only one data type defined in the architect. Thi…

(The above example uses the first iteration of this “project”, the RecordLinkExpression field) As per Reinier’s remark, this statement is incorrect, I was mislead by the wrapper process component.

The component in fact uses the DataStructure_DataType + RecordLink field combination.

[Reinier]

Miroslav,

What you are claiming is incorrect. This proces component does use the datatype + recordlink field combination. Please review the proces component in M6615 to verify.

I simply made it more accessible, by creating one simple Mixed parameter, that the process component converts to the desired datatype + recordlink combination.

[Reinier]

Hi Joachim,

No this field currently only sets the one record reference field.

[j.batzke]

Another question for @m.gechev

Let’s say I link my application log to “saleslines:load(123)” via the record reference.
How should my filter expression look for a grid on the page of any salesline that shows all application logs for a specific sales line?

{applicationlogs, this, this.record_reference.equals(?)}

[m.gechev]

Hi Joachim,

What you ask is explained in this Wiki for how to link records based on expression strings

Basically:

• On the application logs record you need to implement the plugin function from the expression tools plugin
• On the grid of application logs on your saleslines record - you use this function as filter expression. For parameter you need to pass context_object (basically the salesline record you are looking at)

[j.batzke]

For those who are wondering, these are the exact steps that you need to perform to set up a filter for application log records with the new approach:

1. Make sure that you have the “Expression tools plugin” revision 115202 or higher added to your component.
2. Use the process “N_Application log - Write log with dynamic record reference” as mentioned above to write your logs.
3. Make sure that you consume the concept N_ApplicationLog and create a virtual page for it:
   
   
4. Add a new function to the virtual page called “is linked to record()” of the type “boolean”:
   
   
5. Click on the plugin button to apply the “Expression tools” plugin to your new function:
   
   
6. Chose the option “record links to me” from the available options and click OK. Do not worry about the red colors, it should work fine.
   
   
7. Click OK again:
   
   
8. Make sure you consume the feature “N_Record reference v2” for the “N_ApplicationLog” concept:
   
   
9. Right click on your new function and then on “properties”:
   
   
10. Go to the plugin configuration tab and fill in the fields with the consumed features. Then click OK:
    
    
11. Your new function is now ready and can be used anywhere to filter application logs. For example, within other expressions for processes or as a filter for grids of application logs, for example:
    
    

[j.batzke]

Unfortunately, this function has to be rebuilt for every implementation/component, as it is currently not possible to produce and consume parameterized functions.
@Wilko is working on it, and once it will be possible the steps above do not have to be performed and one can just consume the parameterized function “is linked to record(record_to_compare_with)”

[Jesse]

@j.batzke Hey, what if I don’t find record_reference required? In my specific case I want it to be Nullable.

[j.batzke]

If you do not want to link your application log to any record, then just add a new application log record “manually” with an ADD action. You do not need the process then. Make sure to consume and set the “log message”, “log type” and “data source” of the N_Application log.