Feature/17600 exceptions 2024.3 (#127)

Exception Improvements

content/en/docs/2024.3/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md

@@ -200,7 +200,7 @@ The exceptions thrown by the block can be found below:
 | [PropertyNullException][] | Thrown when [Structure][Structure Property] is `null`. |
 | [PropertyEmptyException][] | Thrown when [Structure][Structure Property] does not contain any items. |
 | [XmlSerializationException][] | Thrown when [Structure][Structure Property] has a key that is an empty string. |
-|| Thrown when the [Structure][Structure Property] includes an xml declaration key (e.g. `"?xml"` can only accept the following attributes: `"@version"`, `"@encoding"` and `"@standalone"`.) or a document type definition key (e.g. `"!DOCTYPE"` can only accept the following attributes: `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"`). |
+|| Thrown when the [Structure][Structure Property] includes an invalid xml declaration key (e.g. `"?xml"` can only accept the following attributes: `"@version"`, `"@encoding"` and `"@standalone"`.) or an invalid document type definition key (e.g. `"!DOCTYPE"` can only accept the following attributes: `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"`). |
 || Thrown when the [Structure][Structure Property] includes an xml declaration key (e.g. `"?xml"`) with an attribute that has an invalid [Basic Data Type][Basic Data Types]. (e.g. `Key: "@version", Value: false`, where `"@version"` must be a numeric value). |
 || Thrown when the [Structure][Structure Property] includes a document type definition key (e.g. `"!DOCTYPE"`) that has an attribute with an invalid [Basic Data Type][Basic Data Types]. (e.g. `Key: "@name", Value: 22`, where `"@name"` must be a text value). |
 || Thrown when the [Structure][Structure Property] includes an attribute key with a [Complex Data Type][Complex Data Types] as a value. (e.g. `Key: "@name", Value: new UserCredentials{...}`). |
@@ -220,7 +220,7 @@ If a [Node][Xml Nodes] requires an attribute, the attribute is defined by a [Key
 }
 ```
 
-The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property]
+The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property].
 
 ``` xml
 @"<node attribute="Attribute Value">
@@ -327,7 +327,7 @@ It should be possible to pass the [Xml][Xml Property]  created by this block to
 }
 ```
 
-The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property].
+The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property].
 
 ``` xml
 @"<Cortex_DataTypes_Dictionaries_Structure>

content/en/docs/2024.3/Reference/Exceptions/Xml/_index.md

@@ -1,5 +1,5 @@
 ---
 title: "Xml"
 linkTitle: "Xml"
-description: "Exceptions related to Xml blocks."
+description: "Exceptions related to Xml"
 ---

content/en/docs/2024.3/Reference/Exceptions/Xml/xml-serialization-exception.md

@@ -1,22 +1,113 @@
 ---
 title: "XmlSerializationException"
 linkTitle: "XmlSerializationException"
-description: "The exception thrown when an Xml Serialization errors occur."
+description: "The exception thrown when an error occurs when serializing or deserializing XML."
 ---
 
-
 # {{% param title %}}
 
 <p class="namespace">(Cortex.Exceptions.Xml.XmlSerializationException)</p>
+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}}
+
+## Description
+
+The exception thrown when an error occurs when serializing or deserializing XML.
+
+## Reasons
+
+### Invalid Structure {#structure}
+
+The [Structure][ConvertStructureToXml Structure Property] provided to the [Convert Structure To Xml][ConvertStructureToXml] block is invalid.
+
+#### Message Format
+
+The format of the message can be one of the following:
+
+```json
+"Invalid 'Structure' provided. The 'Structure' has been provided an empty key that could not be converted to valid xml.
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"Invalid 'Structure' provided. The 'Structure' has been provided a key that could not be converted to valid xml.
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"Invalid 'Structure' provided. The 'Structure' has been provided an xml declaration key with an attribute value that could not be converted to valid xml.
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"Invalid 'Structure' provided. The 'Structure' has been provided a document type definition key with an attribute value that could not be converted to valid xml.
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"Invalid 'Structure' provided. The 'Structure' has been provided an attribute key with a value that could not be converted to valid xml.
+Please click the HelpLink for more information on how to fix this."
+```
+
+#### How to fix
 
-TODO: The exception thrown when...
+* Ensure that all keys in the structure provided are not empty (i.e. `""`). The path to the specific key which threw this exception can be seen in the `Key` property (e.g. `"firstItem."` indicates that the empty key is a child of a top level item that has the key `"firstItem"`). If a top level item has an empty key (i.e. `""`), then the `Key` property will also be empty (i.e. `""`).
+* Ensure that the XML declaration key (i.e. `"?xml"`) and document type definition key (i.e. `"!DOCTYPE"`) in the structure provided only have valid attributes:  
+  * XML declaration key: `"@version"`, `"@encoding"` and `"@standalone"`
+  * Document type definition key:  `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"`
 
-The format of the exception message is as follows:
+  The path to the specific key which threw this exception can be seen in the `Key` property.
+* Ensure that all child attribute keys of the XML declaration item, in the structure provided, have values with a valid [Basic Data Type][BasicDataTypes] (e.g. the child attribute key `"@version"`, requires a numeric value like `1.0` or `1.1`, so a value of `false` is invalid).
+* Ensure that all child attribute keys of the document type definition item, in the structure provided, have values with a valid [Basic Data Type][BasicDataTypes] (e.g. the child attribute key `"@name"`, requires a text value like `"exampleName"`, so a value of `22` is invalid).
+* Ensure that all attribute keys in the structure provided have values which are not a [Complex Data Type][ComplexDataTypes]. The path to the specific key which threw this exception can be seen in the `Key` property.
+
+### Invalid XML {#xml}
+
+The [XML][ConvertXmlToStructure XML Property] provided to the [Convert Xml to Structure][ConvertXmlToStructure] block is invalid.
+
+#### Message Format
+
+The format of the message is as follows:
 
 ```json
-TODO: Format
+"Invalid 'Xml' provided. The 'Xml' provided is not valid xml.
+Please click the HelpLink for more information on how to fix this."
 ```
 
-## How to fix
+#### How to fix
+
+Ensure that the [XML][ConvertXmlToStructure XML Property] provided is [valid XML][XmlValidator]. See the `Message` of the `InnerException` property for more information.
+
+## Remarks
+
+### Known Limitations
+
+None
+
+## See Also
+
+### External Documentation
+
+* [XML Validator][XmlValidator]
+
+[Structure]: {{<url path = "Cortex.Reference.DataTypes.Collections.Structure.MainDoc">}}
+
+[ConvertStructureToXml]: {{<url path = "Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml.MainDoc">}}
+[ConvertStructureToXml Structure Property]: {{<url path = "Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml.Structure">}}
+
+[ConvertXmlToStructure]: {{<url path = "Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure.MainDoc">}}
+[ConvertXmlToStructure XML Property]: {{<url path = "Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure.Xml">}}
+
+[XmlNodes]: {{<url path = "W3.XmlNodes">}}
+
+[BasicDataTypes]: {{<url path = "Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.BasicDataTypes">}}
+[ComplexDataTypes]: {{<url path = "Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.ComplexDataTypes">}}
 
-TODO: How to fix...
+[XmlValidator]: {{<url path = "JsonFormatter.XmlValidator">}}

content/en/docs/2024.3/Reference/Exceptions/flows/execution/output-port-not-connected-exception.md

@@ -0,0 +1,46 @@
+---
+title: "OutputPortNotConnectedException"
+linkTitle: "OutputPortNotConnectedException"
+description: "The exception thrown when an execution tries to go through an output port which is not connected."
+---
+
+# {{% param title %}}
+
+<p class="namespace">(Cortex.Exceptions.Flows.Execution.OutputPortNotConnectedException)</p>
+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}}
+
+## Description
+
+The exception thrown when an execution tries to go through an [output port][Block Connections] which is not connected.
+
+## Reasons
+
+### Output port not connected
+
+The [output port][Block Connections] of a block in a flow is not connected to another block.
+
+#### Message Format
+
+The format of the message is as follows:
+
+```json
+"Block output port isn't connected."
+```
+
+#### How to fix
+
+Ensure that the block that threw this exception has its output port connected to another block; see [Block Connections][] for more information.
+
+## Remarks
+
+### Known Limitations
+
+None
+
+## See Also
+
+### External Documentation
+
+None
+
+[Block Connections]: {{<url path = "Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.BlockConnections">}}

content/en/docs/2024.3/Reference/Exceptions/text/_index.md

@@ -1,5 +1,5 @@
 ---
 title: "Text"
 linkTitle: "Text"
-description: "Exceptions related to Text blocks"
+description: "Exceptions related to Text"
 ---

content/en/docs/2024.3/Reference/Exceptions/text/format-exception.md

@@ -0,0 +1,87 @@
+---
+title: "FormatException"
+linkTitle: "FormatException"
+description: "The exception thrown when a format template string is invalid."
+---
+
+# {{% param title %}}
+
+<p class="namespace">(Cortex.Exceptions.Text.FormatException)</p>
+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}}
+
+## Description
+
+The exception thrown when a format template string is invalid.
+
+## Reasons
+
+### Invalid format template
+
+The [format template][Format Templates] provided could not be parsed.
+
+#### Message Format
+
+The format of the message can be one of the following:
+
+```json
+"The largest Format Parameter in '<format-template-property>' is <largest-format-parameter>, therefore, '<values-property>' must contain at least <expected-number-of-values> items, but only contains <number-of-values>.
+Text:
+<format-template-value>
+Values:
+<values-value>
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"'<format-template-property>' contains at least one Format Parameter larger than {0}, therefore, it cannot be formatted.
+Text:
+<format-template-value>
+Please click the HelpLink for more information on how to fix this."
+```
+
+or
+
+```json
+"'<format-template-property>' contains negative Format Parameter(s), therefore, it cannot be formatted.
+Text:
+<format-template-value>
+Please click the HelpLink for more information on how to fix this."
+```
+
+where:
+
+* `<format-template-property>` is the name of the property containing the format template provided for the block which threw this exception; see [Format Text With Value][Format Text With Value Format Template] or [Format Text With Values][Format Text With Values Format Template] for more information.
+* `<format-template-value>` is the value of the format template provided; see [Format Text With Value][Format Text With Value Format Template] or [Format Text With Values][Format Text With Values Format Template] for more information.
+* `<largest-format-parameter>` is the value of the largest unique format specifier provided (i.e. if the format template is `"{0} {2} {1} {3}`, this will be `3`).
+* `<expected-number-of-values>` is the number of values expected to be provided (i.e. if the format template is `"{0} {2} {1} {3}`, this will be `4`).
+* `<values-property>` is the property containing the values provided to insert into the format template.
+* `<values-value>` is the list of values provided to insert into the format template.
+
+#### How to fix
+
+* Ensure that the list of values provided contains at least `<expected-number-of-values>` values (e.g. for a format template of `"{0} {1} {2} {3} {4}"`, there should be at least `5` values provided).
+* Ensure that the format template provided does not have more than 1 format parameter when using the [Format Text With Value][] block.
+* Ensure that the format template provided does not contain any negative format specifiers (e.g. `{-1}`, `{-5}`, `{-1000}`, etc).
+
+## Remarks
+
+### Known Limitations
+
+None
+
+## See Also
+
+### External Documentation
+
+None
+
+[Format Text With Value]: {{<url path = "Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValue.MainDoc">}}
+[Format Text With Value Format Template]: {{<url path="Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValue.FormatTemplate">}}
+[Format Text With Values]: {{<url path = "Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues.MainDoc">}}
+[Format Text With Values Format Template]: {{<url path = "Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues.FormatTemplate">}}
+
+[Working With Text Formatting]: {{<url path = "Cortex.Reference.Concepts.WorkingWith.Text.Formatting.MainDoc">}}
+[Format Specifiers]: {{<url path = "Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatSpecifiers">}}
+[Format Templates]: {{<url path = "Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatTemplates">}}

data/urls.toml

@@ -1054,8 +1054,12 @@
                         KnownLimitations = "/docs/reference/blocks/text/find-and-replace-text/find-and-replace-all-text-block/#known-limitations"
                 [Cortex.Reference.Blocks.Text.FormatText]
                     MainDoc = "/docs/reference/blocks/text/format-text/"
+                    [Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValue]
+                        MainDoc = "/docs/reference/blocks/text/format-text/format-text-with-value-block-1/"
+                        FormatTemplate = "/docs/reference/blocks/text/format-text/format-text-with-value-block-1/#format-template"
                     [Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues]
                         MainDoc = "/docs/reference/blocks/text/format-text/format-text-with-values-block-1/"
+                        FormatTemplate = "/docs/reference/blocks/text/format-text/format-text-with-values-block-1/#format-template"
                 [Cortex.Reference.Blocks.Text.GetText]
                     MainDoc = "/docs/reference/blocks/text/get-text/"
                     [Cortex.Reference.Blocks.Text.GetText.GetTextAtBeginning]
@@ -1120,8 +1124,10 @@
                     MainDoc = "/docs/reference/blocks/xml/convert-xml/"
                     [Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure]
                         MainDoc = "/docs/reference/blocks/xml/convert-xml/convert-xml-to-structure-block/"
+                        Xml = "/docs/reference/blocks/xml/convert-xml/convert-xml-to-structure-block/#xml"
                     [Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml]
                         MainDoc = "/docs/reference/blocks/xml/convert-xml/convert-structure-to-xml-block/"
+                        Structure = "/docs/reference/blocks/xml/convert-xml/convert-structure-to-xml-block/#structure"
         [Cortex.Reference.Dashboards]
             [Cortex.Reference.Observability.Grafana]
                 MainDoc = "/docs/reference/observability/grafana/"
@@ -2302,6 +2308,8 @@
     JsonReaderException = "https://www.newtonsoft.com/json/help/html/T_Newtonsoft_Json_JsonReaderException.htm"
     JsonSerializationException = "https://www.newtonsoft.com/json/help/html/T_Newtonsoft_Json_JsonSerializationException.htm"
     JsonSerializerSettings = "https://www.newtonsoft.com/json/help/html/T_Newtonsoft_Json_JsonSerializerSettings.htm"
+[JsonFormatter]
+    XmlValidator = "https://jsonformatter.org/xml-validator"
 [Kodify]
     WhatIsALoop = "https://kodify.net/csharp/loop/overview-loops/"
 [LetsEncrypt]