Legibility, re-use and configurability

All development work requires troubleshooting, maintenance and extension. Security Directory Integrator solutions are no exception.

We can facilitate this by following a few basic guidelines.

1. Write the AssemblyLines, keeping in mind that others need to understand, use and maintain them. That means to keep ALs as short as possible and naming components clearly and descriptively. Logic implemented in the AL flow through Branches and Loops will be simpler for non-programmers to read and debug than Script 'hidden' in Hooks or packed into Script components.
2. A corollary to the Short AL rule is to keep script snippets short as well. Instead of writing monolithic blocks of code, divide these into smaller units, even putting these into separate Script components to enhance legibility and debug-ability. It is possible then to disable an SC in order to skip code.

   Another way to improve legibility and avoid code duplication is by using Script component inheritance (from the 'Scripts' folder in the Navigator tree-view) and by defining functions for common tasks. An AssemblyLine executes in the context of its own Script engine, so all variables and functions declared in one place are available throughout. A common place to define these is in the AL Prolog Hooks, or in Scripts that have been selected as "Additional Prologs"¹.

3. Choose legibility over elegance when it comes to your algorithms, keeping in mind that when you pick up our own work six months from now, it will probably feel like somebody else's. Consideration for colleagues will be kindness to self as well.
4. Be aware that people with no Configuration Editor skills may need to modify settings and run the AssemblyLines. ALs can be easily started from the command line:

   ibmdisrv –c myConfig.xml –r myAssemblyLine

   This means that we can prepare scripts or batch-files to facilitate this.
5. Make your ALs simpler to reconfigure by externalizing parameter settings by using Properties. Properties are key-value pairs that can be stored in files or databases, and will allow the solution to be reconfigured from outside the Config Editor. Properties are tied to component parameters by clicking on the parameter label and pressing Add property.

   Properties can also be queried and modified from your scripts with the system.getTDIProperty() and system.setTDIProperty() calls, allowing you to make custom logic easily switchable through external property settings as well.

   Properties can furthermore be changed in a running Server by using the command-line utility, bin/tdisrvctl, which also lets you start and stop AssemblyLines, query status and (re)load Configs – all without stopping the Server.

6. As mentioned before, using relative paths for files makes it easier to move the solution to a new installation. It is recommended that you make your paths relative to the directory where the Config XML file is loaded from. This is accessible via the {config.$directory} property, which can then be used to specific path parameters using the Text w/substitution option; for example:

      {config.$directory}/html

7. As mentioned before, but especially when building solutions that will be deployed and run by others, do not anticipate that these users have SDI skills. Provide batch-files/scripts to start the AssemblyLines, including test and validation ALs. These could, for example, simply connect to data sources and report back success or failure. Note that in order to print messages to the console commandline so that your batch-files/scripts return status info, use the Server method, main.logmsg(), instead of the AL version that you used in the tutorial exercises: task.logmsg(). This latter call will only send your message to the log.

These are just a few pointers. More can be found in other SDI literature and in the newsgroups.

Parent topic:

Hardening your Integration Solutions

¹ Additional Prologs are executed before any of the AssemblyLine's own Prolog Hooks are invoked. These are selected in the AssemblyLine Settings panel which can be accessed by right-clicking on an AL and selecting AssemblyLine Settings...