Workflow script tasks best practices

Recommendation

Write well documented and organized code.

Impact

  • Improve readability of the code.
  • Make the script easy to understand and debug.

Recommended action

  • Be consistent in following the naming conventions.
    • Choose and stick with consistent naming conventions for the variables and methods.
    • The recommended style is camelCase.
  • Use descriptive names for both variables and methods. For example:
    • dom1 versus newGlossaryDomain
    • assetIds() versus getAssetIdsFromList()
  • Use indentation for code blocks, such as conditionals, loops and method body.
    • Although indentation is not required for Groovy scripting when indicating code blocks, it drastically improves the readability of the code.
  • Add descriptions as comments for each method and a code block.

  • Add more explicit error messages to handle errors.
    AvoidRecommended
  • Add logging in the script.
    • Logging in the appropriate places can make debugging easier. Use prefixes to set your code log apart from other workflows or log information so that it is easy to find out where the code has been interrupted. This will prevent confusion in projects with parallel development or multiple vendors working and logging on different workflows.
      • prefix = "Workflow Name >>>"
      • prefix_task = "Task Name >>>"
      • At the beginning of the script ("${prefix} ${prefix_task} start")
      • Per important block in the script ("${prefix} ${prefix_task} ${block_message}")
      • At the end of the script ("${prefix} ${prefix_task} end")
    • Clean up development logging when the development phase is over to improve performance and use of the log file. You can also use a global variable and some logic in your scripts to enable or disable extra loggers you have implemented in the development phase. That could ease a future debug in case of issues.
    • There are different levels of loggerApi you can define to see more details in the log-file depends on the Logger Level:
      • loggerApi.info
      • loggerApi.warn
      • loggerApi.error
      • loggerApi.debug

Warning Never log sensitive information, as logs are public and visible to all console users

    Additional information

    For more information see the following resources: