Logic blocks are built on the Logic Builder page in the Logic Block Builder application.
Use the Set Values action to define variables at the start of the logic block configuration rather than in the middle. After a variable is defined, it can be used in subsequent actions. Defining variables at the top makes them easy to locate and helps other application developers that interact with your logic block to know what variables are used.
Your logic block should be efficiently organized and modular. Evaluate your logic blocks for duplicates to ensure that no two logic blocks are accomplishing the same goal.
When developing the logic block, the Logic block inputs and outputs framework should be used where possible, even when modularizing the code. Even though modularization, makes the logic block more readable and easier to maintain, the performance of the logic could be poor because of the amount of refetching that might need to happen. By using the inputs and outputs framework, it can help eliminate the need to refetch tables, which in turn will make the logic block more performant.
Rather than specifying an entire Header Detail (HD) structure, it is more performant to use logic block inputs and outputs to pass specific data sources which you need for your logic block. Only use the entire HD Structure when it is necessary. For example, logic blocks built over Header Detail applications must be built over the HD Structure. Any logic blocks called after that logic block, however, can be developed without specifying the structure. Learn more in Logic block inputs and outputs.
As you are designing a logic block, consider how new logic can be added to an existing application. New logic can be added by:
- Attaching the new logic to an application's existing logic. Ensure that the new logic is added to the structure in a location where the new logic is relevant.
- Creating a fit-for-purpose logic block centered specifically around the new logic if the new logic is substantial or does not fit with the existing logic of the application.
Comments are automatically generated for each logic action.
Add a comment block only if the section needs additional explanation.
Try and keep logic blocks no more than 100 lines, unless it's used as an Action Block, which then the best practice is 150 lines or less. The number of lines represents the number of active actions, that count does not include comments or disabled actions.
Avoid too many nested statements. The more nested statements, the more complex the logic block is to read and maintain. Modularize or flatten the code so the nesting is not too large.
A single set action should be used for common assignments. For example, when mapping output values from one logic block to another, use a single set action for multiple fields. Do not create a single set action for each assignment. The fewer actions in a logic block the better it will perform.
Conditional actions best practices
These best practices ensure that logic block conditional actions are built consistently throughout Nextworld.
A Conditional should always have actions in the true branch. The false branch does not always need an action and can be left empty. If possible, don't structure conditional expressions so that only a false case is used.
You can build your logic block so that conditional actions reside, or nest, within other conditional actions. Build logic blocks so that conditional actions are not deeply nested within one another. Logic blocks that contain several conditional actions nested within one another can be difficult to read and debug. If your logic block contains deeply nested conditional actions, consider calling another logic block.
When you are using conditional logic block actions to enable or disable fields, configure the conditionals to have both the Enable and Disable actions if you only want the current detail row to have enabled or disabled fields. If you want fields on all the rows to be disabled or enabled the same way, you only need one of the conditions.
When you are using active or inactive workflow in your conditional, keep in mind customers can customize workflow and add approvals or extra steps. To prevent unintentional behavior, consider how your conditional checks for the status:
- State Type equals
Active - State Type is not equal to
Inactive
Depending on the situation, you may process records unintentionally. For example, if a workflow is delivered with active and inactive state types only and your conditional is set to 'not equal to Inactive', when a customer creates an approval step, the state type is pending and will go into the True section of your conditional.
Insert/Update Records action best practices
These best practices ensure that logic block Insert and Update Record actions are built consistently throughout Nextworld.
Do not insert or update tables that are outside of the logic block's product family. Call a logic block within that product family instead.
Place the Update Records action inside the database fetch action to update each record that it loops through. If you place the Update Records action outside of the fetch action, the only record that gets updated is the last one the fetch looped through.
Logic block comment best practices
Comments are created automatically by the system for each logic action. Additional comments can also be manually added to explain things such as the intent, and use of that logic block.
Select the Advanced Action toggle in the Logic Builder to see more details about the logic block. Well designed logic blocks generally should not warrant additional comments.
Comments should not be used to repeat information that can be learned from the logic block actions, dictate task numbers, or as a change log.
If the logic block is not easy to use and understand, consider updating the logic block instead of using comments.
Create Message action best practices
These best practices ensure that logic block Create Message actions are built consistently throughout Nextworld.
When displaying an error message using the Create Message action or Interrupt with Error action, you should add Inputs in the Log Data section and an Error Source to provide more information to the user. For example, if a GL Account is no longer active, display which GL Account. If a row has an error and the line number of the row is available, display the value of the line number. The Error Source should be used to highlight the field in the application so the user can see which field is causing an error.
If the error message displays an input for Org Unit, also display Company and Org Unit Number since the organizational unit may not be unique in Nextworld.
Learn more in the Create Message action topic.
If displaying Org Unit in your input, include the following in the specified order:
Org Unit Number
Org Unit
CompanyNumber
CompanyName
Call a logic block action best practices
These best practices ensure that the Call a Logic Block actions are built consistently throughout Nextworld.
When you use a Call a Logic Block action, use one of the following actions for On Error section of that call that appears in the Logic Block panel. You can use a Set Message to set an error or warning for the On Error, but you can also use the Show Called Logic Block Messages action. If you have a specific error you want the user to see based on the failure of that called logic block, use the Set Message action. If you just want to show the error that the called logic block has configured, use the Show Called Logic Block Messages action.
Loop conditional best practices
These best practices ensure that logic block loop conditional actions are built consistently throughout Nextworld.
Make sure that you have an exit condition when using a Loop Conditional. Without an exit condition, the logic times out and you receive an error. For example, if using the conditional Variable <= 10, then the variable must decrement the variable in the loop.
Date and DateTime logic block best practices
These best practices ensure that logic block Date and DateTime actions are built consistently throughout Nextworld.
Always check that Date or DateTime fields are not empty before doing any Date or DateTime comparison. If it is empty, or null, you get a null date error. When dates are in logic blocks they are in UTC time zone. For example, if the user selects a date in the UI, that date would be in the browser's time zone. Once inside the logic block, that date will be represented in UTC. Logic blocks are unaware of a browser's time zone and there is no ability to set a date to the browser's time zone inside a logic block. The best practices below address handling comparisons and conversions.
DateTime to Date
It is often necessary to convert a DateTime data item to a Date in logic for defaults, validations, or retrieval of data with effectivity dates. This can be done using either a Set Values action or a DateTime Decomposition action in logic blocks. Learn more about the Set Values action in the Set Values action topic and the DateTime Decomposition action in the Date and Date Time calculations topic.
- When doing financial reporting, conversions from a DateTime to a Date should always be done using the company's time zone. Similarly, when retrieving exchange rates, the DateTime of a transaction should always be converted to the Company’s time zone for the exchange rate effective date.
- For conversions of DateTime to Date that are not for financial reporting or exchange rates, the following rules should be used:
- If the table has an Organizational Unit field, the input time zone should be the organizational unit’s time zone.
- If the table does not have an Organizational Unit field but has a Company field, the input time zone should be the company’s time zone.
- If the table does not have either an Organizational Unit or Company field, the input time zone should be the tenant time zone.
Date to DateTime
It is often necessary to convert a Date data item to a DateTime data item in logic for temporal reporting where a report is ran for a specific Start Date and End Date, and the data is stored using Date Times. It is recommended to use the DateTime Composition action in these instances, and not the Set Values action in logic blocks. The DateTime Composition action will take the Time Zone into account. Learn more about the DateTime Composition action in the Date and Date Time calculations topic. See the ShippedNotClosedFlatExecution logic block for an example of how to properly use a Date to a DateTime.
- When converting a financial date to a date-time format, default to the company's standard time zone.
- For all other date conversions, use the organizational unit's standard time zone if specified. If not, default to the company's standard time zone.
- Grouping for Temporal Reports
- If a temporal report includes multiple companies and/or organizational units, group the data by organizational unit to ensure consistent reporting within the same time zone.
- For financial reports, group the data by company and adhere to the company's standard time zone.
- Start Date and End Date Conversions
- When a temporal report uses a start and/or end date and relies on data stored in a date-time format:
- The start date must be converted to a date-time with a time of 00:00:00.0000 in the time zone determined using the Time Zone Standards above.
- The end date must be converted to a date-time with a time of 23:59:59.9999 in the time zone determined using the Time Zone Standards above.