From b7aa2d698b54ce2a7795f00455d4137f0ffef1aa Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 7 Nov 2023 11:17:32 +0000 Subject: [PATCH 1/5] Initial commit --- docs/standards/low-code-workflow-naming.md | 74 ++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/standards/low-code-workflow-naming.md diff --git a/docs/standards/low-code-workflow-naming.md b/docs/standards/low-code-workflow-naming.md new file mode 100644 index 00000000..a3e7da4b --- /dev/null +++ b/docs/standards/low-code-workflow-naming.md @@ -0,0 +1,74 @@ +--- +layout: standard +order: 1 +title: Low code workflow naming +date: 2023-11-01 # this should be the date that the content was most recently amended or formally reviewed +id: SEGAS-00012 # Set unique ID for standard +# use `tags: []` for no tags +# Check https://ho-cto.github.io/engineering-guidance-and-standards/tags/ for existing tags +# Note: tags must use sentence case capitalisation +tags: + - Low code + - Software design + - Azure Logic Apps + - Microsoft Power Automate + - AWS Step Functions + - Oracle Integration Cloud +--- + + +Ensuring clean and clear naming in low-code workflow tools helps provide structure and maintainability. This covers a variety of aspects from workflow and action names to scope blocks and error handling. This standard aims to provide generic rules that can be applied across all platforms, however due to the nature of low-code technology and tooling-specific limitations, there may be exceptional circumstances where they cannot be applied. + + +--- + +## Requirement(s) + + + +- [Naming conventions MUST be consistent](#requirement-1) +- [Acronyms or uncommon abbreviations MUST be defined in a central or project glossary](#requirement-2) +- [Workflow, action step and scope block names MUST be descriptive and convey the purpose or objective](#requirement-3) +- [Workflow, action step and scope block names MUST begin with a verb to describe the function, followed by the subject of the verb](#requirement-4) +- [Words in a workflow name MUST be separated by a space where possible](#requirement-5) +- [Scope blocks that are used for error handling MUST be prefixed with the word 'Try' or 'Catch'](#requirement-6) + +### Naming conventions MUST be consistent + +Naming conventions must be applied consistently across a service. Consistency helps ensure maintainability and avoids confusion where multiple conventions are used in the same environment. + +### Acronyms or uncommon abbreviations MUST be defined in a central or project glossary + +Acronyms or abbreviations should only be used where it's not feasible or practical to use the full expansion. They should be defined in a either a central or project glossary accessible to all engineers on the service. Names with unknown acronyms or abbreviations can be meaningless and cause confusion for new engineers working on the service. + +### Workflow, action step and scope block names MUST be descriptive and convey the purpose or objective + +Naming workflows according to their purpose or objective allows engineers to understand the functionality of each workflow at a high level, without having to study the individual steps contained within it. The more functionality a workflow contains, the higher level the name will have to be. + +### Workflow, action step and scope block names MUST begin with a verb to describe the function, followed by the subject of the verb + +The naming of workflows, action steps and scope blocks to begin with a verb, followed by the subject of the verb, ensures clarity on what the component is doing. For example, 'Get case record'; 'Set variable to true'. This makes it easier to understand the purpose without looking at specific low-level logic. + +### Words in a workflow name MUST be separated by a space where possible + +Separating words using spaces makes workflow names more readable. In instances where spaces are not permitted on a platform, dashes or underscores can be used as an alternative. + +### Scope blocks that are used for error handling MUST be prefixed with the word 'Try' or 'Catch' + +Where a scope block is error handled, it should be prefixed with the word 'Try'. Where a scope block provides error handling, it should be prefixed with the word 'Catch'. This allows engineers to see easily, where error handling is applied within a workflow. Other naming standards should still be applied as normal. + +--- \ No newline at end of file From 4353db1515b2f2cc84b08140f7a51a355a6cc549 Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Wed, 15 Nov 2023 13:45:16 +0000 Subject: [PATCH 2/5] fix h3 links --- docs/standards/low-code-workflow-naming.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/standards/low-code-workflow-naming.md b/docs/standards/low-code-workflow-naming.md index a3e7da4b..d261176a 100644 --- a/docs/standards/low-code-workflow-naming.md +++ b/docs/standards/low-code-workflow-naming.md @@ -40,12 +40,12 @@ External links follow standard markdown formatting: -- [Naming conventions MUST be consistent](#requirement-1) -- [Acronyms or uncommon abbreviations MUST be defined in a central or project glossary](#requirement-2) -- [Workflow, action step and scope block names MUST be descriptive and convey the purpose or objective](#requirement-3) -- [Workflow, action step and scope block names MUST begin with a verb to describe the function, followed by the subject of the verb](#requirement-4) -- [Words in a workflow name MUST be separated by a space where possible](#requirement-5) -- [Scope blocks that are used for error handling MUST be prefixed with the word 'Try' or 'Catch'](#requirement-6) +- [Naming conventions MUST be consistent](#naming-conventions-must-be-consistent) +- [Acronyms or uncommon abbreviations MUST be defined in a central or project glossary](#acronyms-or-uncommon-abbreviations-must-be-defined-in-a-central-or-project-glossary) +- [Workflow, action step and scope block names MUST be descriptive and convey the purpose or objective](#workflow%2C-action-step-and-scope-block-names-must-be-descriptive-and-convey-the-purpose-or-objective) +- [Workflow, action step and scope block names MUST begin with a verb to describe the function, followed by the subject of the verb](#workflow%2C-action-step-and-scope-block-names-must-begin-with-a-verb-to-describe-the-function%2C-followed-by-the-subject-of-the-verb) +- [Words in a workflow name MUST be separated by a space where possible](#words-in-a-workflow-name-must-be-separated-by-a-space-where-possible) +- [Scope blocks that are used for error handling MUST be prefixed with the word 'Try' or 'Catch'](#scope-blocks-that-are-used-for-error-handling-must-be-prefixed-with-the-word-%E2%80%98try%E2%80%99-or-%E2%80%98catch%E2%80%99) ### Naming conventions MUST be consistent From e5422c1eee984bc00c866182c05d864a39acc63f Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Wed, 15 Nov 2023 13:45:43 +0000 Subject: [PATCH 3/5] set ID to TBC --- docs/standards/low-code-workflow-naming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standards/low-code-workflow-naming.md b/docs/standards/low-code-workflow-naming.md index d261176a..2d608b29 100644 --- a/docs/standards/low-code-workflow-naming.md +++ b/docs/standards/low-code-workflow-naming.md @@ -3,7 +3,7 @@ layout: standard order: 1 title: Low code workflow naming date: 2023-11-01 # this should be the date that the content was most recently amended or formally reviewed -id: SEGAS-00012 # Set unique ID for standard +id: SEGAS-TBC # Set unique ID for standard # use `tags: []` for no tags # Check https://ho-cto.github.io/engineering-guidance-and-standards/tags/ for existing tags # Note: tags must use sentence case capitalisation From 5a8eddd65f13a552a118e5b9076994acd2b64e1a Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Wed, 15 Nov 2023 13:46:06 +0000 Subject: [PATCH 4/5] remove tech stacks from tags --- docs/standards/low-code-workflow-naming.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/standards/low-code-workflow-naming.md b/docs/standards/low-code-workflow-naming.md index 2d608b29..d0871e88 100644 --- a/docs/standards/low-code-workflow-naming.md +++ b/docs/standards/low-code-workflow-naming.md @@ -10,10 +10,6 @@ id: SEGAS-TBC # Set unique ID for standard tags: - Low code - Software design - - Azure Logic Apps - - Microsoft Power Automate - - AWS Step Functions - - Oracle Integration Cloud --- From 3504f680a73bb812574a7bb4f1b7f69ef36f45b4 Mon Sep 17 00:00:00 2001 From: Aaron Robinson <71637619+ARobinson26@users.noreply.github.com> Date: Wed, 15 Nov 2023 15:16:24 +0000 Subject: [PATCH 5/5] Update ID and review date --- docs/standards/low-code-workflow-naming.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/standards/low-code-workflow-naming.md b/docs/standards/low-code-workflow-naming.md index d0871e88..e0f3f02c 100644 --- a/docs/standards/low-code-workflow-naming.md +++ b/docs/standards/low-code-workflow-naming.md @@ -2,8 +2,8 @@ layout: standard order: 1 title: Low code workflow naming -date: 2023-11-01 # this should be the date that the content was most recently amended or formally reviewed -id: SEGAS-TBC # Set unique ID for standard +date: 2023-11-15 # this should be the date that the content was most recently amended or formally reviewed +id: SEGAS-00012 # Set unique ID for standard # use `tags: []` for no tags # Check https://ho-cto.github.io/engineering-guidance-and-standards/tags/ for existing tags # Note: tags must use sentence case capitalisation @@ -67,4 +67,4 @@ Separating words using spaces makes workflow names more readable. In instances w Where a scope block is error handled, it should be prefixed with the word 'Try'. Where a scope block provides error handling, it should be prefixed with the word 'Catch'. This allows engineers to see easily, where error handling is applied within a workflow. Other naming standards should still be applied as normal. ---- \ No newline at end of file +---