Flow(Innovation) to open a dialog. If the menu item is not present, it means that the `FeatureFlags` in the `CortexGateway.SetParameters.xml` file was not set properly when installing Gateway. See [Troubleshooting][Troubleshooting No Innovation] for more information.
+1. Inside the group, click the `+` button again and click on Flow(Innovation) to open a dialog. If the menu item is not present, it means that the `FeatureFlags` in the `CortexGateway.SetParameters.xml` file was not set properly when updating Gateway. See [Troubleshooting][Troubleshooting No Innovation] for more information.
1. Enter a name for the flow, configure the `Permission Groups` and click `OK` to create the flow.
-1. The flow should be displayed with a start flow block and end flow block. A list of block palettes should be displayed down the left hand side:
+1. The flow should be displayed with a start flow block and end flow block, if those blocks are not displayed see [Troubleshooting][Troubleshooting Flow No Blocks]. A list of block palettes should be displayed down the left hand side:
{{< figure src="/images/New Innovation Flow View.PNG" title="New Flow - Number of palettes may differ" >}}
1. Add a `Set Variable` block and connect it between the start and end blocks.
1. Click the `Set Variable` block to open the Property Editor.
1. Set the `Value` property to the expression `DateTimeOffset.Now`.
1. Type `Result` into the `Variable` property and click `Create Result`.
1. In the Variable Editor, set `Is Output Variable?` to `true` for the new `Result` variable.
-1. Set a breakpoint on the end block and start the flow. An execution token should appear, the `Result` variable should show the current time. If the token does not appear, try refreshing the page.
+1. Set a breakpoint on the end block and start the flow. An execution token should appear, the `Result` variable should show the current time. If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][Troubleshooting Flow Not Starting].
1. Continue or stop the execution.
1. Commit the flow.
@@ -55,6 +55,8 @@ Test the platform by creating a new flow and executing it using the following st
1. {{% ctx %}} Innovation has now been verified and is ready to use.
[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}}
+[Troubleshooting Flow Not Starting]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNotStarting" >}}
+[Troubleshooting Flow No Blocks]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNoBlocks" >}}
[Troubleshooting No Innovation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingNoInnovation" >}}
[Troubleshooting No Publish]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingNoPublish" >}}
[Troubleshooting Root Certificate Error]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingNoRootCertificate" >}}
diff --git a/content/en/docs/2023.7/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server.md b/content/en/docs/2023.7/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server.md
index c65c60c6c..496903b93 100644
--- a/content/en/docs/2023.7/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server.md
+++ b/content/en/docs/2023.7/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server.md
@@ -182,9 +182,9 @@ To install the components required for debugging, perform the steps detailed in
|`ServiceFabricApiGatewayBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Application Servers][Configure Installation Script]; if so, this value must be configured to the one used.(Cortex.Blocks.Dictionaries.AddItem.AddItemWithKeyBlock`3)
+ +## Description + +Adds an [Item][Item Property] to a [Dictionary][Dictionary Property] with the specified [Key][Key Property]. + +## Examples + +### Add an Item to an empty Dictionary + +This example will add `1` to `{}` with a key of `"Key1"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Item][Item Property] | `($)Item`, with value `1` | `($)Item` is a variable of type [Int32][] | + +#### Result + +Adding `1` to `{}` with a key of `"Key1"` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 1} +``` + +*** + +### Add an Item to a Dictionary + +This example will add `2` to `{"Key1" : 1}` with a key of `"Key2"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key2"` | `($)Key` is a variable of type [String][] | +| [Item][Item Property] | `($)Item`, with value `2` | `($)Item` is a variable of type [Int32][] | + +#### Result + +Adding `2` to `{"Key1" : 1}` with a key of `"Key2"` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 1, "Key2" : 2} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] where the [Item][Item Property] is added with the specified [Key][Key Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] to add the [Item][Item Property] with. + +Keys cannot be `null` and must be unique within a dictionary, as they are used to lookup the item they correspond to. + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Item + +The [Item][Item Property] to be added to the [Dictionary][Dictionary Property] with the specified [Key][Key Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Item][Item Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [KeyPresentException][] | Thrown when an item with the specified [Key][Key Property] is already present. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[KeyPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeyPresentException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/_index.md new file mode 100644 index 000000000..18d91f743 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Contains Item(s)" +linkTitle: "Contains Item(s)" +description: "Check if an item or multiple items are contained in a dictionary." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-and-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-and-value-block-3.md new file mode 100644 index 000000000..361824949 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-and-value-block-3.md @@ -0,0 +1,192 @@ +--- +title: "Contains Item With Key And Value" +linkTitle: "Contains Item With Key And Value" +description: "Checks if a Dictionary contains at least one item with the specified key and matching the specified value." +--- + +{{< figure src="/blocks/dictionaries-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithKeyAndValueBlock`3)
+ +## Description + +Checks if [Dictionary][Dictionary Property] contains at least one item with the specified [Key][Key Property] and matching the specified [Value][Value Property]. + +## Examples + +### Dictionary contains item with Key and Value + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with the key `"Key1"` and value `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains one item with the key `Key1` and value `1`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +true +``` + +*** + +### Dictionary does not contain item with Key and Value + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with the key `"Key1"` and value `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Value][Value Property] | `($)Value`, with value `10` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains one item with the key `"Key1"`, but its value is not `10`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to check whether it contains at least one item with the specified [Key][Key Property] and matching [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] to check for matching items. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Value + +The [Value][Value Property] to check for matching items. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Item + +The result of the contains item check. + +If [Dictionary][Dictionary Property] contains at least one item with the specified [Key][Key Property] and matching [Value][Value Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItem` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Contains Item][ContainsItem Property] property is set to `false`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[Value Property]: {{< ref "#value" >}} +[ContainsItem Property]: {{< ref "#contains-item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-block-3.md new file mode 100644 index 000000000..6a47e7df1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-block-3.md @@ -0,0 +1,167 @@ +--- +title: "Contains Item With Key" +linkTitle: "Contains Item With Key" +description: "Checks if a Dictionary contains at least one item with the specified key." +--- + +{{< figure src="/blocks/dictionaries-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithKeyBlock`3)
+ +## Description + +Checks if [Dictionary][Dictionary Property] contains at least one item with the specified [Key][Key Property]. + +## Examples + +### Dictionary contains item with Key + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with the key `"Key1"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains one item with the key `Key1`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +true +``` + +*** + +### Dictionary does not contain item with Key + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with the key `"Key10"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key10"` | `($)Key` is a variable of type [String][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` does not contain any items with the key `"Key10"`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to check whether it contains at least one item with the specified [Key][Key Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] to check for matching items. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Item + +The result of the contains item check. + +If [Dictionary][Dictionary Property] contains at least one item with the specified [Key][Key Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItem` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Contains Item][ContainsItem Property] property is set to `false`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[ContainsItem Property]: {{< ref "#contains-item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-value-block-3.md new file mode 100644 index 000000000..a976ada81 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-value-block-3.md @@ -0,0 +1,169 @@ +--- +title: "Contains Item With Value" +linkTitle: "Contains Item With Value" +description: "Checks if a Dictionary contains at least one item matching the specified value." +--- + +{{< figure src="/blocks/dictionaries-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithValueBlock`3)
+ +## Description + +Checks if [Dictionary][Dictionary Property] contains at least one item matching [Value][Value Property]. + +## Examples + +### Dictionary contains item with Value + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains the value `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains two items with the value `1`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +true +``` + +*** + +### Dictionary does not contain item with Value + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains the value `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `10` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` does not contain any items with the value `10`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to check whether it contains at least one item matching the specified [Value][Value Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] to check for matching items. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Item + +The result of the contains item check. + +If [Dictionary][Dictionary Property] contains at least one item matching the specified [Value][Value Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItem` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Contains Item][ContainsItem Property] property is set to `false`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} +[ContainsItem Property]: {{< ref "#contains-item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-keys-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-keys-block-3.md new file mode 100644 index 000000000..4b1dc3610 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-keys-block-3.md @@ -0,0 +1,174 @@ +--- +title: "Contains Items With Keys" +linkTitle: "Contains Items With Keys" +description: "Checks if a Dictionary contains at least one item with each of the specified keys." +--- + +{{< figure src="/blocks/dictionaries-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemsWithKeysBlock`3)
+ +## Description + +Checks if [Dictionary][Dictionary Property] contains at least one item with each of the specified [Keys][Keys Property]. + +## Examples + +### Dictionary contains items with Keys + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with each of the keys in `["Key1", "Key2", "Key3"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Keys][Keys Property] | `($)Keys`, with value `["Key1", "Key2", "Key3"]` | `($)Keys` is a variable of type [IEnumerable][]<[String][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item matching each of the values in `["Key1", "Key2", "Key3"]`; it contains one item with the key `"Key1"`, one item with the key `"Key2"` and one item with the key `"Key3"`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +true +``` + +*** + +### Dictionary does not contain items with Keys + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item with each of the keys in `["Key1", "Key2", "Key3", "Key10"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Keys][Keys Property] | `($)Keys`, with value `["Key1", "Key2", "Key3", "Key10"]` | `($)Keys` is a variable of type [IEnumerable][]<[String][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` does not contain at least one item matching each of the values in `["Key1", "Key2", "Key3"]`; it contains one item with the key `"Key1"`, one item with the key `"Key2"` and one item with the key `"Key3"`, but no items with the key `"Key10"`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to check whether it contains at least one item with each of the specified [Keys][Keys Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Keys + +The [Keys][Keys Property] to check for matching items. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TKey][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Items + +The result of the contains items check. + +If [Dictionary][Dictionary Property] contains at least one item with each of the specified [Keys][Keys Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItems` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentNullException][] | Thrown when any key in [Keys][Keys Property] is `null`| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Keys][Keys Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Empty Keys + +If [Keys][Keys Property] is empty (i.e. `[]`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Keys Property]: {{< ref "#keys" >}} +[ContainsItems Property]: {{< ref "#contains-items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-values-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-values-block-3.md new file mode 100644 index 000000000..ad2cfd5d6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-values-block-3.md @@ -0,0 +1,170 @@ +--- +title: "Contains Items With Values" +linkTitle: "Contains Items With Values" +description: "Checks if a Dictionary contains at least one item matching each of the specified values." +--- + +{{< figure src="/blocks/dictionaries-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemsWithValuesBlock`3)
+ +## Description + +Checks if [Dictionary][Dictionary Property] contains at least one item matching each of the specified [Values][Values Property]. + +## Examples + +### Dictionary contains items with Values + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item matching each of the values in `[1, 2, 3]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item matching each of the values in `[1, 2, 3]`; it contains two items with the value `1`, two items with the value `2` and two items with the value `3`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +true +``` + +*** + +### Dictionary does not contain items with Values + +This example will check whether `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` contains at least one item matching each of the values in `[1, 2, 3, 10]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3, 10]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` does not contain at least one item matching each of the values in `[1, 2, 3, 10]`; it contains two items with the value `1`, two items with the value `2` and two items with the value `3`, but no items with the value `10`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to check whether it contains at least one item matching each of the specified [Values][Values Property]. + +Items are considered matching if they have a value matching one of the specified [Values][Values Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Values + +The [Values][Values Property] to check for matching items. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Items + +The result of the contains items check. + +If [Dictionary][Dictionary Property] contains at least one item matching each of the specified [Values][Values Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItems` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Values][Values Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Values Property]: {{< ref "#values" >}} +[ContainsItems Property]: {{< ref "#contains-items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/_index.md new file mode 100644 index 000000000..ec65cd646 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Count(s) of Items" +linkTitle: "Get Count(s) of Items" +description: "Get the count(s) of items in a dictionary." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-all-items-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-all-items-block-3.md new file mode 100644 index 000000000..80273366c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-all-items-block-3.md @@ -0,0 +1,116 @@ +--- +title: "Get Count Of All Items" +linkTitle: "Get Count Of All Items" +description: "Gets the count of all items in a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetCount.GetCountOfAllItemsBlock`3)
+ +## Description + +Gets the [Count][Count Property] of all items in a [Dictionary][Dictionary Property]. + +## Examples + +### Get Count of all items in a Dictionary + +This example will get the count of all items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Count][Count Property] | `($)Count`, with no value | `($)Count` is a variable that will be set to an [Int32][] value | + +#### Result + +Getting the count of all items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Count` being updated to the following: + +```json +6 +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get the [Count][Count Property] of all items for. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Count + +The [Count][Count Property] of all items in [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Count][Count Property] property is set to `0`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Count Property]: {{< ref "#count" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-items-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-items-with-value-block-3.md new file mode 100644 index 000000000..78527d7ae --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-count-of-items-with-value-block-3.md @@ -0,0 +1,146 @@ +--- +title: "Get Count Of Items With Value" +linkTitle: "Get Count Of Items With Value" +description: "Gets the count of items in a Dictionary with the specified value." +--- + +{{< figure src="/blocks/dictionaries-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetCount.GetCountOfItemsWithValueBlock`3)
+ +## Description + +Gets the [Count][Count Property] of items in a [Dictionary][Dictionary Property] with the specified [Value][Value Property]. + +## Examples + +### Get Count of items in a Dictionary with a Value + +This example will get the count of items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` with the value `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Count][Count Property] | `($)Count`, with no value | `($)Count` is a variable that will be set to an [Int32][] value | + +#### Result + +Getting the count of items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` with the value `1` results in the variable `($)Count` being updated to the following: + +```json +2 +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get the [Count][Count Property] of items with the specified [Value][Value Property] for. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] items must match to be included in the [Count][Count Property]. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Count + +The [Count][Count Property] of items in [Dictionary][Dictionary Property] with the specified [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`), the variable specified in the [Count][Count Property] property is set to `0`. + +### No items matching Value + +If [Dictionary][Dictionary Property] does not contain items matching the specified [Value][Value Property], the variable specified in the [Count][Count Property] property is set to `0`. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} +[Count Property]: {{< ref "#count" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-counts-of-items-with-values-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-counts-of-items-with-values-block-3.md new file mode 100644 index 000000000..6237debae --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-count/get-counts-of-items-with-values-block-3.md @@ -0,0 +1,151 @@ +--- +title: "Get Counts Of Items With Values" +linkTitle: "Get Counts Of Items With Values" +description: "Gets the counts of items in a Dictionary matching each of the specified values." +--- + +{{< figure src="/blocks/dictionaries-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetCount.GetCountsOfItemsWithValuesBlock`3)
+ +## Description + +Gets the [Counts][Counts Property] of items in a [Dictionary][Dictionary Property] matching each of the specified [Values][Values Property]. + +## Examples + +### Get Counts of items in a Dictionary matching each of the Values + +This example will get the counts of items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` matching each of the values `[1, 2, 3]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Counts][Counts Property] | `($)Counts`, with no value | `($)Counts` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +Getting the counts of items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` matching each of the values `[1, 2, 3]` results in the variable `($)Counts` being updated to the following: + +```json +[2, 2, 2] +``` + +The counts of items matching each value are added to `($)Counts` at the same [index][Indexes] the value is in `($)Values`. In this example, there are two items matching the first value `1`, two items matching the second value `2` and two items matching the third value `3`, resulting in `($)Counts` being set to `[2, 2, 2]`. + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get the [Counts][Counts Property] of items matching each of the specified [Values][Values Property] for. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Values + +The [Values][Values Property] items must match to be included in the [Counts][Counts Property]. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Counts + +The [Counts][Counts Property] of items in [Dictionary][Dictionary Property] matching each of the specified [Values][Values Property]. + +For each value in [Values][Values Property], [Counts][Counts Property] will have a corresponding item whose value is the count of items in [Dictionary][Dictionary Property] matching the value. + +I.e. The count of items matching the first value in [Values][Values Property] will be saved as the first item in [Counts][Counts Property]; the count of items matching the second value in [Values][Values Property] will be saved as the second item in [Counts][Counts Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[Int32][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Counts` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Values][Values Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`), the variable specified in the [Counts][Counts Property] property is set to empty (i.e. `[]`). + +### No items matching a specified value in Values + +If [Dictionary][Dictionary Property] does not contain items matching one of the specified [Values][Values Property], `0` is written to the corresponding item in [Counts][Counts Property] for that value. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Values Property]: {{< ref "#values" >}} +[Counts Property]: {{< ref "#counts" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/_index.md new file mode 100644 index 000000000..9a60abac1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Item(s)" +linkTitle: "Get Item(s)" +description: "Get an item or multiple items from a dictionary." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-all-items-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-all-items-block-3.md new file mode 100644 index 000000000..e0a826a97 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-all-items-block-3.md @@ -0,0 +1,116 @@ +--- +title: "Get All Items" +linkTitle: "Get All Items" +description: "Gets all items from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-get-all-items-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetItem.GetAllItemsBlock`3)
+ +## Description + +Get all [Items][Items Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Get all items from a Dictionary + +This example will get all items in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[Int32][]> | + +#### Result + +Getting all items from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Items` being updated to the following: + +```json +[1, 2, 3, 3, 2, 1] +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get all [Items][Items Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Items + +The [Items][Items Property] in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) the variable specified in the [Items][Items Property] property is set to an empty [IList][]<[TItem][]> (i.e. `[]`). + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-item-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-item-with-key-block-3.md new file mode 100644 index 000000000..faa9ea684 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-item-with-key-block-3.md @@ -0,0 +1,202 @@ +--- +title: "Get Item With Key" +linkTitle: "Get Item With Key" +description: "Gets the specified occurrence of an item with the given key from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetItem.GetItemWithKeyBlock`3)
+ +## Description + +Gets the specified [Occurrence][Occurrence Property] of an [Item][Item Property] with the given [Key][Key Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Get the first Occurrence of an Item with a Key from a Dictionary + +This example will attempt to get the first occurrence of an item with the key `"Key1"` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [Int32][]) | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means get the first occurrence; `2` means second etc. + +Attempting to get the first occurrence of an item with the key `"Key1"` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Item` being updated to the following: + +```json +1 +``` + +*** + +### Get the last Occurrence of an Item with a Key from a Dictionary + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to get an occurrence of item with that key. + +This example will illustrate this, by attempting to get the last occurrence of an item with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [Int32][]) | + +#### Result + +An [Occurrence][Occurrence Property] of `-1` means get the last occurrence; `-2` means second last etc. + +Attempting to get the last occurrence of an item with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}` results in the variable `($)Item` being updated to the following: + +```json +10 +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get the specified [Occurrence][Occurrence Property] of [Item][Item Property] with the given [Key][Key Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the [Item][Item Property] to get must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching [Item][Item Property] to get from the [Dictionary][Dictionary Property]. + +Items are considered matching if they have the specified [Key][Key Property]. + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Item + +The specified [Occurrence][Occurrence Property] of [Item][Item Property] with the given [Key][Key Property] from [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Item` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [KeyNotPresentException][] | Thrown when the [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [OccurrenceNotPresentException][] | Thrown when the specified [Occurrence][Occurrence Property] of [Item][Item Property] with the given [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Occurrences + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[KeyNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeyNotPresentException.MainDoc" >}} +[OccurrenceNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Collections.OccurrenceNotPresentException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-items-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-items-with-key-block-3.md new file mode 100644 index 000000000..7223d31a2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-item/get-items-with-key-block-3.md @@ -0,0 +1,145 @@ +--- +title: "Get Items With Key" +linkTitle: "Get Items With Key" +description: "Gets all items with the given key from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetItem.GetItemsWithKeyBlock`3)
+ +## Description + +Gets all [Items][Items Property] with the given [Key][Key Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Get all Items with a Key from a Dictionary + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to get all items with that key. + +This example will illustrate this, by attempting to get all items with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[Int32][]> | + +#### Result + +Attempting to get all items with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}` results in the variable `($)Items` being updated to the following: + +```json +[1, 10] +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get all [Items][Items Property] with the given [Key][Key Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the [Items][Items Property] to get must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Items + +All [Items][Items Property] with the given [Key][Key Property] in [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [KeyNotPresentException][] | Thrown when the [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[KeyNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeyNotPresentException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/_index.md new file mode 100644 index 000000000..d0504c442 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Key(s)" +linkTitle: "Get Key(s)" +description: "Get a key or multiple keys from a dictionary." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/get-all-keys-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/get-all-keys-block-3.md new file mode 100644 index 000000000..eef70a953 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/get-key/get-all-keys-block-3.md @@ -0,0 +1,116 @@ +--- +title: "Get All Keys" +linkTitle: "Get All Keys" +description: "Gets all keys from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-get-all-keys-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.GetKey.GetAllKeysBlock`3)
+ +## Description + +Get all [Keys][Keys Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Get all keys from a Dictionary + +This example will get all keys in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Keys][Keys Property] | `($)Keys`, with no value | `($)Keys` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Getting all keys from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Keys` being updated to the following: + +```json +["Key1", "Key2", "Key3", "Key4", "Key5", "Key6"] +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to get all [Keys][Keys Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Keys + +The [Keys][Keys Property] in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TKey][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Keys` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) the variable specified in the [Keys][Keys Property] property is set to an empty [IList][]<[TKey][]> (i.e. `[]`). + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Keys Property]: {{< ref "#keys" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/_index.md new file mode 100644 index 000000000..a516b96dd --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Remove Item(s)" +linkTitle: "Remove Item(s)" +description: "Remove an item or multiple items from a dictionary." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-all-items-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-all-items-block-3.md new file mode 100644 index 000000000..2311ef94d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-all-items-block-3.md @@ -0,0 +1,121 @@ +--- +title: "Remove All Items" +linkTitle: "Remove All Items" +description: "Removes all items from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveAllItemsBlock`3)
+ +## Description + +Removes all items from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove all items from an empty Dictionary + +This example will attempt to remove all items from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | + +#### Result + +Attempting to remove all items from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove all items from a Dictionary + +This example will remove all items from `{"Key1" : 1, "Key2" : 2}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | + +#### Result + +Removing all items from `{"Key1" : 1, "Key2" : 2}` results in the variable `($)Dictionary` being updated to the following: + +```json +{} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] where all items are removed from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-key-block-3.md new file mode 100644 index 000000000..7deff3b7f --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-key-block-3.md @@ -0,0 +1,216 @@ +--- +title: "Remove Item With Key" +linkTitle: "Remove Item With Key" +description: "Removes the specified occurrence of an item with the given key from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemWithKeyBlock`3)
+ +## Description + +Removes the specified [Occurrence][Occurrence Property] of an item with the given [Key][Key Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove the first Occurrence of an item with a Key from an empty Dictionary + +This example will attempt to remove the first occurrence of an item with the key `"Key1"` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +Attempting to remove the first occurrence of an item with the key `"Key1"` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove the first Occurrence of an item with a Key from a Dictionary + +This example will attempt to remove the first occurrence of an item with the key `"Key1"` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means remove the first occurrence; `2` means second etc. + +Attempting to remove the first occurrence of an item with the key `"Key1"` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} +``` + +*** + +### Remove the last Occurrence of an item with a Key from a Dictionary + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to remove any occurrence of item with that key. + +This example will illustrate this, by attempting to remove the last occurrence of an item with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1` means remove the last occurrence; `-2` means second last etc. + +Attempting to remove the last occurrence of an item with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` results in the variable `($)Dictionary` being updated to the following: + +```csharp +{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove the specified [Occurrence][Occurrence Property] of item with the given [Key][Key Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the item to remove must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to remove from the [Dictionary][Dictionary Property]. + +Items are considered matching if they have the specified [Key][Key Property]. + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Occurrences + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### No items with given Key, or Occurrence is not present + +If [Dictionary][Dictionary Property] does not contain items with the given [Key][Key Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-value-block-3.md new file mode 100644 index 000000000..395f8848e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-value-block-3.md @@ -0,0 +1,213 @@ +--- +title: "Remove Item With Value" +linkTitle: "Remove Item With Value" +description: "Removes the specified occurrence of an item matching a value from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemWithValueBlock`3)
+ +## Description + +Removes the specified [Occurrence][Occurrence Property] of an item matching a [Value][Value Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove the first Occurrence of an item matching a Value from an empty Dictionary + +This example will attempt to remove the first occurrence of an item matching the value `1` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +Attempting to remove the first occurrence of an item matching the value `1` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove the first Occurrence of an item matching a Value from a Dictionary + +This example will attempt to remove the first occurrence of an item matching the value `1` from `{"Key1" : 1, "Key2" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means remove the first occurrence; `2` means second etc. + +Attempting to remove the first occurrence of an item matching the value `1` from `{"Key1" : 1, "Key2" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key2" : 1} +``` + +*** + +### Remove the last Occurrence of an item matching a Value from a Dictionary + +This example will attempt to remove the last occurrence of an item matching the value `1` from `{"Key1" : 1, "Key2" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means remove the last occurrence; `-2` means second last etc. + +Attempting to remove the last occurrence of an item matching the value `1` from `{"Key1" : 1, "Key2" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 1} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove the specified [Occurrence][Occurrence Property] of matching item from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] the item to remove must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to remove from the [Dictionary][Dictionary Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Occurrences + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### No items matching Value, or Occurrence is not present + +If [Dictionary][Dictionary Property] does not contain items matching the specified [Value][Value Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-key-block-3.md new file mode 100644 index 000000000..2a901a429 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-key-block-3.md @@ -0,0 +1,162 @@ +--- +title: "Remove Items With Key" +linkTitle: "Remove Items With Key" +description: "Removes all items with the given key from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKeyBlock`3)
+ +## Description + +Removes all items with the given [Key][Key Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove all items with a Key from an empty Dictionary + +This example will attempt to remove all items with the key `"Key1"` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | + +#### Result + +Attempting to remove all items with the key `"Key1"` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove all items with a Key from a Dictionary + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to remove all items with that key. + +This example will illustrate this, by attempting to remove all items with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | + +#### Result + +Attempting to remove all items with the key `[1]` from `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` results in the variable `($)Dictionary` being updated to the following: + +```csharp +{[2] : 2, [3] : 3, [3] : 3, [2] : 2} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove all items with the given [Key][Key Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the items to remove must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### No items with given Key + +If [Dictionary][Dictionary Property] does not contain items with the given [Key][Key Property] there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-keys-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-keys-block-3.md new file mode 100644 index 000000000..e0404792d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-keys-block-3.md @@ -0,0 +1,167 @@ +--- +title: "Remove Items With Keys" +linkTitle: "Remove Items With Keys" +description: "Removes all items with any of the given keys from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKeysBlock`3)
+ +## Description + +Removes all items with any of the given [Keys][Keys Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove all items with any of the given Keys from an empty Dictionary + +This example will attempt to remove all items with any of the given keys in `["Key1", "Key2"]` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Keys][Keys Property] | `($)Keys`, with value `["Key1", "Key2"]` | `($)Keys` is a variable of type [IDictionary][]<[String][]> | + +#### Result + +Attempting to remove all items with any of the given keys in `["Key1", "Key2"]` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove all items with any of the given Keys from a Dictionary + +This example will attempt to remove all items with any of the given keys in `["Key1", "Key2"]` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Keys][Keys Property] | `($)Keys`, with value `["Key1", "Key2"]` | `($)Keys` is a variable of type [IDictionary][]<[String][]> | + +#### Result + +Attempting to remove all items with any of the given keys in `["Key1", "Key2"]` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove all items with any of the given [Keys][Keys Property] from. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Keys + +The [Keys][Keys Property] the items to remove must have one of. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TKey][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentNullException][] | Thrown when any key in [Keys][Keys Property] is `null`| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Keys][Keys Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### Empty Keys + +If [Keys][Keys Property] is empty (i.e. `[]`) there are no keys to match, therefore nothing can be removed and no operation is performed. + +### No items with one of the given Keys + +If [Dictionary][Dictionary Property] does not contain items with one of the given [Keys][Keys Property], there is nothing to remove for that key. + +### No items with any of the given Keys + +If [Dictionary][Dictionary Property] does not contain items with any of the given [Keys][Keys Property] there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Keys Property]: {{< ref "#keys" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-value-block-3.md new file mode 100644 index 000000000..b5df28e3d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-value-block-3.md @@ -0,0 +1,161 @@ +--- +title: "Remove Items With Value" +linkTitle: "Remove Items With Value" +description: "Removes all items matching a value from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValueBlock`3)
+ +## Description + +Removes all items matching a [Value][Value Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove all items matching a Value from an empty Dictionary + +This example will attempt to remove all items matching the value `1` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | + +#### Result + +Attempting to remove all items matching the value `1` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove all items matching a Value from a Dictionary + +This example will attempt to remove all items matching the value `1` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | + +#### Result + +Attempting to remove all items matching the value `1` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove all matching items from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] the items to remove must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### No items matching Value + +If [Dictionary][Dictionary Property] does not contain items matching the specified [Value][Value Property], there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-values-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-values-block-3.md new file mode 100644 index 000000000..bfdf294cc --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-values-block-3.md @@ -0,0 +1,164 @@ +--- +title: "Remove Items With Values" +linkTitle: "Remove Items With Values" +description: "Removes all items matching one of the specified values from a Dictionary." +--- + +{{< figure src="/blocks/dictionaries-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValuesBlock`3)
+ +## Description + +Removes all items matching one of the specified [Values][Values Property] from a [Dictionary][Dictionary Property]. + +## Examples + +### Remove all items matching one of the specified Values from an empty Dictionary + +This example will attempt to remove all items matching one of the values `[1, 2]` from `{}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{}` | `($)Dictionary` is a variable of type [IDictionary][]<[dynamic][], [dynamic][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to remove all items matching one of the values `[1, 2]` from `{}` results in no operation, as there is nothing to remove. Therefore, the variable `($)Dictionary` remains: + +```json +{} +``` + +*** + +### Remove all items matching one of the specified Values from a Dictionary + +This example will attempt to remove all items matching one of the values `[1, 2]` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to remove all items matching one of the values `[1, 2]` from `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key3" : 3, "Key4" : 3} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to remove all matching items from. + +Items are considered matching if they have one of the specified [Values][Values Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Values + +The [Values][Values Property] the items to remove must match one of. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Values][Values Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to remove, so no operation is performed. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`) there are no values to match, therefore nothing can be removed and no operation is performed. + +### No items matching a specified value in Values + +If [Dictionary][Dictionary Property] does not contain items matching one of the specified [Values][Values Property], there is nothing to remove for that value. + +### No items matching Values + +If [Dictionary][Dictionary Property] does not contain items matching any of the specified [Values][Values Property], there is nothing to remove, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Values Property]: {{< ref "#values" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/_index.md new file mode 100644 index 000000000..56379859a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Set Item(s)" +linkTitle: "Set Item(s)" +description: "Set an item or multiple items in a dictionary to a new value." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-all-items-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-all-items-block-3.md new file mode 100644 index 000000000..5c50db8a6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-all-items-block-3.md @@ -0,0 +1,123 @@ +--- +title: "Set All Items" +linkTitle: "Set All Items" +description: "Sets all items in a Dictionary to a new value." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetAllItemsBlock`3)
+ +## Description + +Sets all items in a [Dictionary][Dictionary Property] to a [New Value][NewValue Property]. + +## Examples + +### Set all items in a Dictionary to a New Value + +This example will set all items in `{"Key1" : 1, "Key2" : 2}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | + +#### Result + +Setting all items in `{"Key1" : 1, "Key2" : 2}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set all items in. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### New Value + +The [New Value][NewValue Property] to set all items in [Dictionary][Dictionary Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to set, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-key-block-3.md new file mode 100644 index 000000000..87d635b1c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-key-block-3.md @@ -0,0 +1,211 @@ +--- +title: "Set Item With Key" +linkTitle: "Set Item With Key" +description: "Sets the specified occurrence of an item with the given key in a Dictionary to a new value." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemWithKeyBlock`3)
+ +## Description + +Sets the specified [Occurrence][Occurrence Property] of an item with the given [Key][Key Property] in a [Dictionary][Dictionary Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the first Occurrence of an item with a Key in a Dictionary to a New Value + +This example will attempt to set the first occurrence of an item with the key `"Key1"` in `{"Key1" : 1, "Key2" : 2}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `"Key1"` | `($)Key` is a variable of type [String][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means set the first occurrence; `2` means second etc. + +Attempting to set the first occurrence of an item with the key `"Key1"` in `{"Key1" : 1, "Key2" : 2}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 1} +``` + +*** + +### Set the last Occurrence of an item with a Key in a Dictionary to a New Value + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to set an occurrence of item with that key. + +This example will illustrate this, by attempting to set the last occurrence of an item with the key `[1]` in `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means set the last occurrence; `-2` means second last etc. + +Attempting to set the last occurrence of an item with the key `[1]` in `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```csharp +{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set the specified [Occurrence][Occurrence Property] of item with the given [Key][Key Property] in. + +Items are considered matching if they have the specified [Key][Key Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the item to set must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set the specified [Occurrence][Occurrence Property] of item with the given [Key][Key Property] in [Dictionary][Dictionary Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of item with the given [Key][Key Property] to set in the [Dictionary][Dictionary Property]. + +Items are considered matching if they have the specified [Key][Key Property]. + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [KeyNotPresentException][] | Thrown when the [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [OccurrenceNotPresentException][] | Thrown when the specified [Occurrence][Occurrence Property] of item with the given [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Occurrences + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[NewValue Property]: {{< ref "#new-value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[KeyNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeyNotPresentException.MainDoc" >}} +[OccurrenceNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Collections.OccurrenceNotPresentException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-value-block-3.md new file mode 100644 index 000000000..c665ff4f7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-item-with-value-block-3.md @@ -0,0 +1,206 @@ +--- +title: "Set Item With Value" +linkTitle: "Set Item With Value" +description: "Sets the specified occurrence of an item matching a value in a Dictionary to a new value." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemWithValueBlock`3)
+ +## Description + +Sets the specified [Occurrence][Occurrence Property] of an item matching a [Value][Value Property] in a [Dictionary][Dictionary Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the first Occurrence of an item matching a Value in a Dictionary to a New Value + +This example will attempt to set the first occurrence of an item matching the value `1` in `{"Key1" : 1, "Key2" : 1}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means set the first occurrence; `2` means second etc. + +Attempting to set the first occurrence of an item matching the value `1` in `{"Key1" : 1, "Key2" : 1}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 1} +``` + +*** + +### Set the last Occurrence of an item matching a Value in a Dictionary to a New Value + +This example will attempt to set the last occurrence of an item matching the value `1` in `{"Key1" : 1, "Key2" : 1}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means set the last occurrence; `-2` means second last etc. + +Attempting to set the last occurrence of an item matching the value `1` in `{"Key1" : 1, "Key2" : 1}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 1, "Key2" : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set the specified [Occurrence][Occurrence Property] of matching item in. + +Items are considered matching if they have the specified [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] the item to set must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set the specified [Occurrence][Occurrence Property] of matching item in [Dictionary][Dictionary Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to set in the [Dictionary][Dictionary Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] or [New Value][NewValue Property] are `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Occurrences + +Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to set, so no operation is performed. + +### No items matching Value, or Occurrence is not present + +If [Dictionary][Dictionary Property] does not contain items matching the specified [Value][Value Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to set, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} +[NewValue Property]: {{< ref "#new-value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-key-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-key-block-3.md new file mode 100644 index 000000000..8ec4ef0e0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-key-block-3.md @@ -0,0 +1,155 @@ +--- +title: "Set Items With Key" +linkTitle: "Set Items With Key" +description: "Sets all items with the given key in a Dictionary to a new value." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithKeyBlock`3)
+ +## Description + +Sets all items with the given [Key][Key Property] in a [Dictionary][Dictionary Property] to a [New Value][NewValue Property]. + +## Examples + +### Sets all items with a Key in a Dictionary to a New Value + +Typically keys are simple data types such as [String][], [Int32][], [Boolean][], and for these a dictionary cannot the same key value more than once. This is due to how the data type's object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference). + +However, other data types such as [IList][]<[Int32][]> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to set all items with that key. + +This example will illustrate this, by attempting to set all items with the key `[1]` in `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[IList][]<[Int32][]>, [Int32][]> | +| [Key][Key Property] | `($)Key`, with value `[1]` | `($)Key` is a variable of type [IList][]<[Int32][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | + +#### Result + +Attempting to set all items with the key `[1]` in `{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```csharp +{[1] : 10, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set all items with the given [Key][Key Property] in. + +Items are considered matching if they have the specified [Key][Key Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Key + +The [Key][Key Property] the items to set must have. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +For information about what a key is, please see [Keys][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TKey][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set all items with the given [Key][Key Property] in [Dictionary][Dictionary Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [KeyNotPresentException][] | Thrown when the [Key][Key Property] is not present in the [Dictionary][Dictionary Property]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Key][Key Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether a key is already present, please see [Object Equality][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Key Property]: {{< ref "#key" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[KeyNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeyNotPresentException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-keys-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-keys-block-3.md new file mode 100644 index 000000000..db087c543 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-keys-block-3.md @@ -0,0 +1,150 @@ +--- +title: "Set Items With Keys" +linkTitle: "Set Items With Keys" +description: "Sets all items with any of the given keys in a Dictionary to new values." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithKeysBlock`3)
+ +## Description + +Sets all items with any of the given [Keys][Keys Property] in a [Dictionary][Dictionary Property] to [New Values][NewValues Property]. + +## Examples + +### Set all items with any of the given Keys in a Dictionary to New Values + +This example will attempt to set all items with any of the keys `["Key1", "Key2"]` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `[10, 20]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Keys][Keys Property] | `($)Keys`, with value `["Key1", "Key2"]` | `($)Keys` is a variable of type [IEnumerable][]<[String][]> | +| [NewValues][NewValues Property] | `($)NewValues`, with value `[10, 20]` | `($)NewValues` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to set all items with any of the keys `["Key1", "Key2"]` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `[10, 20]` respectively, results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 20, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set all matching items in. + +Items are considered matching if they have any of the specified [Keys][Keys Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | +### Keys + +The [Keys][Keys Property] the items to set must have one of. + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TKey][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Values + +The [New Values][NewValues Property] to set the items with the corresponding [Keys][Keys Property] in [Dictionary][Dictionary Property] to. + +The number of items in [New Values][NewValues Property] must match the number of items in [Keys][Keys Property]. + +[Dictionary][Dictionary Property] items with the first key in [Keys][Keys Property] will be set to the first value in [New Values][NewValues Property]; [Dictionary][Dictionary Property] items with the second key in [Keys][Keys Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentNullException][] | Thrown when any key in [Keys][Keys Property] is `null`| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [KeysNotPresentException][] | Thrown when any key in the [Keys][Keys Property] is not present in the [Dictionary][Dictionary Property]. | +| [PropertyItemCountException][] | Thrown when the count of items in [Keys][Keys Property] and the count of items in [New Values][NewValues Property] are not the same, or neither contain any items. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Keys][Keys Property] or [New Values][NewValues Property] are `null`. | + +## Remarks + +### Key Equality + +For information and examples of how it is determined whether an item has a specified key, please see [Object Equality][]. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Keys Property]: {{< ref "#keys" >}} +[NewValues Property]: {{< ref "#new-values" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[KeysNotPresentException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.KeysNotPresentException.MainDoc" >}} +[PropertyItemCountException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyItemCountException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-value-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-value-block-3.md new file mode 100644 index 000000000..e75267cff --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-value-block-3.md @@ -0,0 +1,152 @@ +--- +title: "Set Items With Value" +linkTitle: "Set Items With Value" +description: "Sets all items matching a value in a Dictionary to a new value." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithValueBlock`3)
+ +## Description + +Sets all items matching a [Value][Value Property] in a [Dictionary][Dictionary Property] to a [New Value][NewValue Property]. + +## Examples + +### Set all items matching a Value in a Dictionary to a New Value + +This example will attempt to set all items matching the value `1` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | + +#### Result + +Attempting to set all items matching the value `1` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `10` results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set all matching items in. + +Items are considered matching if they have the specified [Value][Value Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Value + +The [Value][Value Property] the items to set must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set all matching items in [Dictionary][Dictionary Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] or [New Value][NewValue Property] are `null` and [Dictionary][Dictionary Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to set, so no operation is performed. + +### No items matching Value + +If [Dictionary][Dictionary Property] does not contain items matching the specified [Value][Value Property], there is nothing to set, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Value Property]: {{< ref "#value" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-values-block-3.md b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-values-block-3.md new file mode 100644 index 000000000..2162102a8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Dictionaries/set-item/set-items-with-values-block-3.md @@ -0,0 +1,160 @@ +--- +title: "Set Items With Values" +linkTitle: "Set Items With Values" +description: "Sets all items matching one of the specified values in a Dictionary to new values." +--- + +{{< figure src="/blocks/dictionaries-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithValuesBlock`3)
+ +## Description + +Set all items matching one of the specified [Values][Values Property] in a [Dictionary][Dictionary Property] to [New Values][NewValues Property]. + +## Examples + +### Set all items matching one of the specified Values in a Dictionary to New Values + +This example will attempt to set all items matching one of the values `[1, 2]` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `[10, 20]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Dictionary][Dictionary Property] | `($)Dictionary`, with value `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` | `($)Dictionary` is a variable of type [IDictionary][]<[String][], [Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [NewValues][NewValues Property] | `($)NewValues`, with value `[10, 20]` | `($)NewValues` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to set all items matching one of the values `[1, 2]` in `{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}` to `[10, 20]` respectively, results in the variable `($)Dictionary` being updated to the following: + +```json +{"Key1" : 10, "Key2" : 20, "Key3" : 3, "Key4" : 3, "Key5" : 20, "Key6" : 10} +``` + +*** + +## Properties + +### Dictionary + +The [Dictionary][Dictionary Property] to set all matching items in. + +Items are considered matching if they have one of the specified [Values][Values Property]. + +[Dictionary][Dictionary Property] can be any [IDictionary][]<[TKey][], [TItem][]>, where [TKey][] represents the type of keys used to lookup items in the [Dictionary][Dictionary Property], and [TItem][] represents the type of items in the [Dictionary][Dictionary Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[TKey][], [TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Dictionary` with no value | + +### Values + +The [Values][Values Property] the items to set must match one of. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Values + +The [New Values][NewValues Property] to set the items matching the corresponding [Values][Values Property] in [Dictionary][Dictionary Property] to. + +The number of items in [New Values][NewValues Property] must match the number of items in [Values][Values Property]. + +[Dictionary][Dictionary Property] items matching the first value in [Values][Values Property] will be set to the first value in [New Values][NewValues Property]; [Dictionary][Dictionary Property] items matching the second value in [Values][Values Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyDictionaryException][] | Thrown when [Dictionary][Dictionary Property] is read-only. | +| [DuplicateValueException][] | Thrown when [Values][Values Property] contains duplicate values. | +| [PropertyItemCountException][] | Thrown when the count of items in [Values][Values Property] and the count of items in [New Values][NewValues Property] are not the same, or neither contain any items. | +| [PropertyNullException][] | Thrown when [Dictionary][Dictionary Property] or [Values][Values Property] or [New Values][NewValues Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Dictionary + +If [Dictionary][Dictionary Property] is empty (i.e. `{}`) there is nothing to set, so no operation is performed. + +### No items matching a specified value in Values + +If [Dictionary][Dictionary Property] does not contain items matching one of the specified [Values][Values Property], there is nothing to set for that value. + +### No items matching Values + +If [Dictionary][Dictionary Property] does not contain items matching any of the specified [Values][Values Property], there is nothing to set, so no operation is performed. + +### Defining dictionaries using literal syntax + +For information about how to define dictionaries using literal syntax, see [Dictionary Literals][]. + +### Defining dictionaries using expression syntax + +For information about how to define dictionaries using expression syntax, see [Create a Dictionary<TKey, TItem>][]. + +### Dictionaries containing items with same data types vs different data types + +For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see [Dictionaries][]. + +[Dictionary Property]: {{< ref "#dictionary" >}} +[Values Property]: {{< ref "#values" >}} +[NewValues Property]: {{< ref "#new-values" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Dictionary Literals]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DictionaryLiteral" >}} +[Create a Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Dictionaries]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Dictionaries" >}} + +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyDictionaryException]: {{< url path="Cortex.Reference.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException.MainDoc" >}} +[DuplicateValueException]: {{< url path="Cortex.Reference.Exceptions.Lists.DuplicateValueException.MainDoc" >}} +[PropertyItemCountException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyItemCountException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/_index.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/_index.md new file mode 100644 index 000000000..517a2760b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/_index.md @@ -0,0 +1,5 @@ +--- +title: "Exceptions" +linkTitle: "Exceptions" +description: "Blocks related to handling and throwing Exceptions." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/_index.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/_index.md new file mode 100644 index 000000000..0b363a866 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/_index.md @@ -0,0 +1,5 @@ +--- +title: "Handle Block Exception(s)" +linkTitle: "Handle Block Exception(s)" +description: "Handle exceptions that occur during block execution." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-block.md new file mode 100644 index 000000000..8fc45900c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-block.md @@ -0,0 +1,132 @@ +--- +title: "Handle Block Exception" +linkTitle: "Handle Block Exception" +description: "Handles any exception thrown by the block it is connected to." +--- + +{{< figure src="/blocks/exceptions-handle-block-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionBlock)
+ +## Description + +Handles any [Exception][Exception Property] thrown by the block it is connected to. + +## Examples + +### Handle and save the Exception + +This example will handle any exception thrown by the block it is connected to; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any exception and save the exception to the `($)Exception` variable for use later in the flow execution. + +*** + +### Handle and discard the Exception from being saved + +This example will handle any exception thrown by the block it is connected to; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any exception, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +## Properties + +### Exception + +The [Exception][Exception Property] that is handled. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +If the flow execution does not need the exception, it can be discarded by assigning the built-in `($)_` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)_` to [discard][] | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Chaining Exception handling blocks + +Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below: + +* [Handle Block Exception Matching Message][] +* [Handle Block Exception Matching Messages][] +* [Handle Block Exception Matching Type Name][] +* [Handle Block Exception Matching Type Names][] +* [Handle Block Exception][] + +{{< figure src="/images/chaining-handle-block-exception-blocks.png" >}} + +Each block has an input port on its left-hand side and, with the exception of this block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block. + +As this block handles any exception, it does not require the output port. + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Why does the Exception property return a dynamic data type? + +The decision for the [Exception][Exception Property] to return a [dynamic data type][dynamic] rather than an [Exception data type][Exception], was to avoid users having to [cast][Object Casting] the exception to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Exception data type][Exception] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the exception to its correct type. + +### Using the built-in ($)_ variable to discard the Exception from being saved + +Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in `($)_` variable to indicate the exception does not need to be saved. + +For more information about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +[Exception Property]: {{< ref "#exception" >}} +[discard]: {{< ref "#using-the-built-in-_-variable-to-discard-the-exception-from-being-saved" >}} + +[Handle Block Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockException.MainDoc" >}} +[Handle Block Exception Matching Message]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessage.MainDoc" >}} +[Handle Block Exception Matching Messages]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessages.MainDoc" >}} +[Handle Block Exception Matching Type Name]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeName.MainDoc" >}} +[Handle Block Exception Matching Type Names]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeNames.MainDoc" >}} +[Discarding Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-message-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-message-block.md new file mode 100644 index 000000000..042d52362 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-message-block.md @@ -0,0 +1,229 @@ +--- +title: "Handle Block Exception Matching Message" +linkTitle: "Handle Block Exception Matching Message" +description: "Handles any exception thrown by the block it is connected to that matches a specified message." +--- + +{{< figure src="/blocks/exceptions-handle-block-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingMessageBlock)
+ +## Description + +Handles any [Exception][Exception Property] thrown by the block it is connected to that matches a specified [Message][Message Property]. + +## Examples + +### Handle Exception containing Message and save the Exception + +This example will handle any exception thrown by the block it is connected to that contains `"'List' is null"` in its `Message` property; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Message][Message Property] | `($)Message`, with value `"'List' is null"` | `($)Message` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any exception containing `"'List' is null"` in its `Message` property and save the exception to the `($)Exception` variable for use later in the flow execution. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's `Message` property would be `"'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing `"'List' is null"` in their `Message`, this exception would be handled and saved to the `($)Exception` variable. + +*** + +### Handle Exception containing Message and discard the Exception + +This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Message][Message Property] | `($)Message`, with value `"'List' is null"` | `($)Message` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any exception containing `"'List' is null"` in its `Message` property, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's `Message` property would be `"'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing `"'List' is null"` in their `Message`, this exception would be handled, but because the `($)_` variable is used it will not be saved to the `($)Exception` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +### Exception does not contain Message + +This example will not handle an exception thrown by the block it is connected to that does not contain `"'List' is null"` in its `Message` property; the exception will be passed to the next exception handling block. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Message][Message Property] | `($)Message`, with value `"'List' is null"` | `($)Message` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that won't be set | + +#### Result + +The block will not handle any exception that does not contain `"'List' is null"` in its `Message` property; instead the exception will be passed to the next exception handling block. + +E.g. + +If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a [CannotModifyReadOnlyListException][] when executed. + +This exception's `Message` property would be `"'List' cannot be modified because it's read-only.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing `"'List' is null"` in their `Message`, this exception would not be handled. + +*** + +## Properties + +### Message + +The [Message][Message Property] the [Exception's][Exception Property] `Message` property must contain for this block to handle the [Exception][Exception Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether [Message][Message Property] is contained in the [Exception's][Exception Property] `Message` property. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Exception + +The [Exception][Exception Property] if it is handled by the block. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +If the flow execution does not need the exception, it can be discarded by assigning the built-in `($)_` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)_` to [discard][] | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Message + +If [Message][Message Property] is `null` or empty (i.e. `""`), and the thrown exception's `Message` property is also `null` or empty (i.e. `""`), the exception will be handled and saved to the variable specified in the [Exception][Exception Property] property. + +### Chaining Exception handling blocks + +Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below: + +* [Handle Block Exception Matching Message][] +* [Handle Block Exception Matching Messages][] +* [Handle Block Exception Matching Type Name][] +* [Handle Block Exception Matching Type Names][] +* [Handle Block Exception][] + +{{< figure src="/images/chaining-handle-block-exception-blocks.png" >}} + +Each block has an input port on its left-hand side and, with the exception of the [Handle Block Exception][] block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block. + +As the [Handle Block Exception][] block handles any exception, it does not require the output port. + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Why does the Exception property return a dynamic data type? + +The decision for the [Exception][Exception Property] to return a [dynamic data type][dynamic] rather than an [Exception data type][Exception], was to avoid users having to [cast][Object Casting] the exception to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Exception data type][Exception] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the exception to its correct type. + +### Using the built-in ($)_ variable to discard the Exception from being saved + +Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in `($)_` variable to indicate the exception does not need to be saved. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +[Message Property]: {{< ref "#message" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Exception Property]: {{< ref "#exception" >}} +[discard]: {{< ref "#using-the-built-in-_-variable-to-discard-the-exception-from-being-saved" >}} + +[Handle Block Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockException.MainDoc" >}} +[Handle Block Exception Matching Message]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessage.MainDoc" >}} +[Handle Block Exception Matching Messages]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessages.MainDoc" >}} +[Handle Block Exception Matching Type Name]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeName.MainDoc" >}} +[Handle Block Exception Matching Type Names]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeNames.MainDoc" >}} +[Discarding Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-messages-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-messages-block.md new file mode 100644 index 000000000..ee0d90231 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-messages-block.md @@ -0,0 +1,233 @@ +--- +title: "Handle Block Exception Matching Messages" +linkTitle: "Handle Block Exception Matching Messages" +description: "Handles any exception thrown by the block it is connected to that matches any message in a given set of messages." +--- + +{{< figure src="/blocks/exceptions-handle-block-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingMessagesBlock)
+ +## Description + +Handles any [Exception][Exception Property] thrown by the block it is connected to that matches any message in a given set of [Messages][Messages Property]. + +## Examples + +### Handle Exception containing any of the Messages and save the Exception + +This example will handle any exception thrown by the block it is connected to that contains any of the messages in `["'List' is null", "'List' is empty"]` in its `Message` property; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Messages][Messages Property] | `($)Messages`, with value `["'List' is null", "'List' is empty"]` | `($)Messages` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any exception containing any of the messages in `["'List' is null", "'List' is empty"]` in its `Message` property and save the exception to the `($)Exception` variable for use later in the flow execution. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's `Message` property would be `"'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing any of `["'List' is null", "'List' is empty"]` in their `Message`, this exception would be handled and saved to the `($)Exception` variable. + +*** + +### Handle Exception containing any of the Messages and discard the Exception + +This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Messages][Messages Property] | `($)Messages`, with value `["'List' is null", "'List' is empty"]` | `($)Messages` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any exception containing any of the messages in `["'List' is null", "'List' is empty"]` in its `Message` property, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's `Message` property would be `"'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing any of `["'List' is null", "'List' is empty"]` in their `Message`, this exception would be handled, but because the `($)_` variable is used it will not be saved to the `($)Exception` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +### Exception does not contain any of the Messages + +This example will not handle an exception thrown by the block it is connected to that does not contain any of `["'List' is null", "'List' is empty"]` in its `Message` property; the exception will be passed to the next exception handling block. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Messages][Messages Property] | `($)Messages`, with value `["'List' is null", "'List' is empty"]` | `($)Messages` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that won't be set | + +#### Result + +The block will not handle any exception that does not contain any of `["'List' is null", "'List' is empty"]` in its `Message` property; instead the exception will be passed to the next exception handling block. + +E.g. + +If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a [CannotModifyReadOnlyListException][] when executed. + +This exception's `Message` property would be `"'List' cannot be modified because it's read-only.\r\nPlease click the HelpLink for more information on how to fix this."`; therefore as we are checking for exceptions containing any of `["'List' is null", "'List' is empty"]` in their `Message`, this exception would not be handled. + +*** + +## Properties + +### Messages + +The [Messages][Messages Property] the [Exception's][Exception Property] `Message` property must contain any of for this block to handle the [Exception][Exception Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingTypeNameBlock)
+ +## Description + +Handles any [Exception][Exception Property] thrown by the block it is connected to that matches a specified [Type Name][TypeName Property]. + +## Examples + +### Handle Exception matching Type Name and save the Exception + +This example will handle any exception thrown by the block it is connected to that contains `"PropertyNull"` in its fully qualified `TypeName`; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of type names. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Name][TypeName Property] | `($)TypeName`, with value `"PropertyNull"` | `($)TypeName` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any exception containing `"PropertyNull"` in its fully qualified `TypeName` and save the exception to the `($)Exception` variable for use later in the flow execution. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Common.Property.PropertyNullException"`; therefore as we are checking for exceptions containing `"PropertyNull"` in their `TypeName`, this exception would be handled and saved to the `($)Exception` variable. + +*** + +### Handle Exception matching Type Name and discard the Exception + +This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of type names. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Name][TypeName Property] | `($)TypeName`, with value `"PropertyNull"` | `($)TypeName` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any exception containing `"PropertyNull"` in its fully qualified `TypeName`, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Common.Property.PropertyNullException"`; therefore as we are checking for exceptions containing `"PropertyNull"` in their `TypeName`, this exception would be handled, but because the `($)_` variable is used it will not be saved to the `($)Exception` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +### Exception does not match Type Name + +This example will not handle an exception thrown by the block it is connected to that does not contain `"PropertyNull"` in its fully qualified `TypeName`; the exception will be passed to the next exception handling block. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of type names. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Name][TypeName Property] | `($)TypeName`, with value `"PropertyNull"` | `($)TypeName` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that won't be set | + +#### Result + +The block will not handle any exception that does not contain `"PropertyNull"` in its fully qualified `TypeName`; instead the exception will be passed to the next exception handling block. + +E.g. + +If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a [CannotModifyReadOnlyListException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Lists.CannotModifyReadOnlyListException"`; therefore as we are checking for exceptions containing `"PropertyNull"` in their `TypeName`, this exception would not be handled. + +*** + +## Properties + +### Type Name + +The [Type Name][TypeName Property] the [Exception's][Exception Property] fully qualified `TypeName` must contain for this block to handle the [Exception][Exception Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `null`) | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether [Type Name][TypeName Property] is contained in the [Exception's][Exception Property] fully qualified `TypeName`. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Exception + +The [Exception][Exception Property] if it is handled by the block. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +If the flow execution does not need the exception, it can be discarded by assigning the built-in `($)_` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)_` to [discard][] | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| [PropertyEmptyException][] | Thrown when [Type Name][TypeName Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Type Name][TypeName Property] is `null`. | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Chaining Exception handling blocks + +Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below: + +* [Handle Block Exception Matching Message][] +* [Handle Block Exception Matching Messages][] +* [Handle Block Exception Matching Type Name][] +* [Handle Block Exception Matching Type Names][] +* [Handle Block Exception][] + +{{< figure src="/images/chaining-handle-block-exception-blocks.png" >}} + +Each block has an input port on its left-hand side and, with the exception of the [Handle Block Exception][] block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block. + +As the [Handle Block Exception][] block handles any exception, it does not require the output port. + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Why does the Exception property return a dynamic data type? + +The decision for the [Exception][Exception Property] to return a [dynamic data type][dynamic] rather than an [Exception data type][Exception], was to avoid users having to [cast][Object Casting] the exception to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Exception data type][Exception] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the exception to its correct type. + +### Using the built-in ($)_ variable to discard the Exception from being saved + +Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in `($)_` variable to indicate the exception does not need to be saved. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +[TypeName Property]: {{< ref "#type-name" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Exception Property]: {{< ref "#exception" >}} +[discard]: {{< ref "#using-the-built-in-_-variable-to-discard-the-exception-from-being-saved" >}} + +[Handle Block Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockException.MainDoc" >}} +[Handle Block Exception Matching Message]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessage.MainDoc" >}} +[Handle Block Exception Matching Messages]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingMessages.MainDoc" >}} +[Handle Block Exception Matching Type Name]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeName.MainDoc" >}} +[Handle Block Exception Matching Type Names]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeNames.MainDoc" >}} +[Discarding Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-names-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-names-block.md new file mode 100644 index 000000000..bbdd7f642 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-names-block.md @@ -0,0 +1,232 @@ +--- +title: "Handle Block Exception Matching Type Names" +linkTitle: "Handle Block Exception Matching Type Names" +description: "Handles any exception thrown by the block it is connected to that matches any type name in a given set of type names." +--- + +{{< figure src="/blocks/exceptions-handle-block-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingTypeNamesBlock)
+ +## Description + +Handles any [Exception][Exception Property] thrown by the block it is connected to that matches any type name in a given set of [Type Names][TypeNames Property]. + +## Examples + +### Handle Exception matching any of the Type Names and save the Exception + +This example will handle any exception thrown by the block it is connected to that contains any of the type names in `["PropertyNull", "PropertyEmpty"]` in its fully qualified `TypeName`; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Names][TypeNames Property] | `($)TypeNames`, with value `["PropertyNull", "PropertyEmpty"]` | `($)TypeNames` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any exception containing any of the type names in `["PropertyNull", "PropertyEmpty"]` in its fully qualified `TypeName` and save the exception to the `($)Exception` variable for use later in the flow execution. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Common.Property.PropertyNullException"`; therefore as we are checking for exceptions containing any of `["PropertyNull", "PropertyEmpty"]` in their `TypeName`, this exception would be handled and saved to the `($)Exception` variable. + +*** + +### Handle Exception containing any of the Type Names and discard the Exception + +This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Names][TypeNames Property] | `($)TypeNames`, with value `["PropertyNull", "PropertyEmpty"]` | `($)TypeNames` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any exception containing any of the type names in `["PropertyNull", "PropertyEmpty"]` in its fully qualified `TypeName`, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +E.g. + +If the List property of the Add Item At Beginning list block was set to null, it would throw a [PropertyNullException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Common.Property.PropertyNullException"`; therefore as we are checking for exceptions containing any of `["PropertyNull", "PropertyEmpty"]` in their `TypeName`, this exception would be handled, but because the `($)_` variable is used it will not be saved to the `($)Exception` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +### Exception does not contain any of the Type Names + +This example will not handle an exception thrown by the block it is connected to that does not contain any of `["PropertyNull", "PropertyEmpty"]` in its fully qualified `TypeName`; the exception will be passed to the next exception handling block. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of messages. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Type Names][TypeNames Property] | `($)TypeNames`, with value `["PropertyNull", "PropertyEmpty"]` | `($)TypeNames` is a variable of type [IEnumerable][]<[String][]> | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that won't be set | + +#### Result + +The block will not handle any exception that does not contain any of `["PropertyNull", "PropertyEmpty"]` in its fully qualified `TypeName`; instead the exception will be passed to the next exception handling block. + +E.g. + +If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a [CannotModifyReadOnlyListException][] when executed. + +This exception's fully qualified `TypeName` is `"Cortex.Exceptions.Lists.CannotModifyReadOnlyListException"`; therefore as we are checking for exceptions containing any of `["PropertyNull", "PropertyEmpty"]` in their `TypeName`, this exception would not be handled. + +*** + +## Properties + +### Type Names + +The [Type Names][TypeNames Property] the [Exception's][Exception Property] fully qualified `TypeName` must contain any of for this block to handle the [Exception][Exception Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Exceptions.HandleFlowException.HandleFlowExceptionWorkspaceBlock)
+ +## Description + +Handles any unhandled [Exception][Exception Property] within the Flow. + +For more information, please see [Unhandled Exceptions][]. + +## Examples + +### Handle and save the Exception + +This example will handle any unhandled exception within the Flow; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any unhandled exception within the Flow and save the exception to the `($)Exception` variable for use later in the flow execution. + +*** + +### Handle and discard the Exception from being saved + +This example will handle any unhandled exception within the Flow; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any unhandled exception within the Flow, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +## Properties + +### Exception + +The [Exception][Exception Property] that is handled. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +By default, this property is assigned the built-in `($)_` variable, so the exception will be discarded. If the flow execution does need the exception, a variable can be assigned to save it in. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)_` to [discard][] | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Block Restrictions + +The following restrictions apply to this block: + +* A flow cannot contain more than one [Handle Flow Exception][] block. +* The [Handle Flow Exception][] block is not available on any palette. +* The [Handle Flow Exception][] block cannot be copied. +* The [Handle Flow Exception][] block cannot be deleted. + +### Unhandled Exceptions + +If an exception thrown by a block is not handled by any connected [Handle Block Exception blocks][], it will be passed to the [Handle Workspace Exception][] block on the same workspace. + +If the workspace does not contain a [Handle Workspace Exception][] block it will be rethrown by the Workspace block the workspace belongs to. + +This process repeats until: + +* The exception is handled, or +* The exception reaches the flow's top-level workspace, is not handled by any [Handle Block Exception blocks][] and the top-level workspace does not contain a [Handle Workspace Exception][] block. At this stage, the exception is handled by the flow's [Handle Flow Exception][] block. + +If an exception occurs within the workspace of the [Handle Flow Exception][] block and is not handled, the flow will end with a status of Error. + +{{< figure src="/images/flow-error-status.png" >}} + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Why does the Exception property return a dynamic data type? + +The decision for the [Exception][Exception Property] to return a [dynamic data type][dynamic] rather than an [Exception data type][Exception], was to avoid users having to [cast][Object Casting] the exception to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Exception data type][Exception] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the exception to its correct type. + +### Using the built-in ($)_ variable to discard the Exception from being saved + +Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in `($)_` variable to indicate the exception does not need to be saved. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +[Exception Property]: {{< ref "#exception" >}} +[discard]: {{< ref "#using-the-built-in-_-variable-to-discard-the-exception-from-being-saved" >}} + +[Unhandled Exceptions]: {{< ref "#unhandled-exceptions" >}} + +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} +[Discarding Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} + +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/_index.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/_index.md new file mode 100644 index 000000000..bfe98fb7b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/_index.md @@ -0,0 +1,5 @@ +--- +title: "Handle Workspace Exception(s)" +linkTitle: "Handle Workspace Exception(s)" +description: "Handle exceptions not handled by any Handle Block Exception blocks." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/handle-workspace-exception-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/handle-workspace-exception-block.md new file mode 100644 index 000000000..b36045815 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/handle-workspace-exception/handle-workspace-exception-block.md @@ -0,0 +1,144 @@ +--- +title: "Handle Workspace Exception" +linkTitle: "Handle Workspace Exception" +description: "Handles any unhandled exception within its workspace." +--- + +{{< figure src="/blocks/exceptions-handle-workspace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.HandleWorkspaceException.HandleWorkspaceExceptionBlock)
+ +## Description + +Handles any unhandled [Exception][Exception Property] within its workspace. + +For more information, please see [Unhandled Exceptions][]. + +## Examples + +### Handle and save the Exception + +This example will handle any unhandled exception within the block's workspace; saving the exception to a variable, so the flow execution can use it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)Exception`, with no value | `($)Exception` is a variable that will be set to a [dynamic][] value | + +#### Result + +The block will handle any unhandled exception within the block's workspace and save the exception to the `($)Exception` variable for use later in the flow execution. + +*** + +### Handle and discard the Exception from being saved + +This example will handle any unhandled exception within the block's workspace; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)_`, with no value | `($)_` is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded | + +#### Result + +The block will handle any unhandled exception within the block's workspace, but will not save the exception as the `($)_` variable indicates it is not needed and can be discarded. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +*** + +## Properties + +### Exception + +The [Exception][Exception Property] that is handled. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +If the flow execution does not need the exception, it can be discarded by assigning the built-in `($)_` variable. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)_` to [discard][] | + + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Block Restrictions + +The following restrictions apply to this block: + +* A workspace cannot contain more than one [Handle Workspace Exception][] block. If more than one is added, it will be reported as a message when trying to debug the flow. +* The [Handle Workspace Exception][] block will only handle the first unhandled exception within its workspace. This is to prevent infinite recursion within the flow. Subsequent unhandled exceptions are passed to the next relevant exception handling block. For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. +* A flow's Top-Level Workspace cannot contain a [Handle Workspace Exception][] block. If one is added, it will be reported as a message when trying to debug the flow. + +### Unhandled Exceptions + +If an exception thrown by a block is not handled by any connected [Handle Block Exception blocks][], it will be passed to the [Handle Workspace Exception][] block on the same workspace. + +If the workspace does not contain a [Handle Workspace Exception][] block it will be rethrown by the [Workspace][] block the workspace belongs to. + +This process repeats until: + +* The exception is handled, or +* The exception reaches the flow's top-level workspace, is not handled by any [Handle Block Exception blocks][] and the top-level workspace does not contain a [Handle Workspace Exception][] block. At this stage, the exception is handled by the flow's [Handle Flow Exception][] block. + +If an exception occurs within the workspace of the [Handle Flow Exception][] block and is not handled, the flow will end with a status of Error. + +{{< figure src="/images/flow-error-status.png" >}} + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Why does the Exception property return a dynamic data type? + +The decision for the [Exception][Exception Property] to return a [dynamic data type][dynamic] rather than an [Exception data type][Exception], was to avoid users having to [cast][Object Casting] the exception to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Exception data type][Exception] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the exception to its correct type. + +### Using the built-in ($)_ variable to discard the Exception from being saved + +Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in `($)_` variable to indicate the exception does not need to be saved. + +For more infomation about using the built-in `($)_` variable, please see [Discarding Output Properties][]. + +[Exception Property]: {{< ref "#exception" >}} +[discard]: {{< ref "#using-the-built-in-_-variable-to-discard-the-exception-from-being-saved" >}} + +[Unhandled Exceptions]: {{< ref "#unhandled-exceptions" >}} + +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} +[Discarding Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} + +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} +[Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.MainDoc" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/_index.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/_index.md new file mode 100644 index 000000000..2867ac09a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/_index.md @@ -0,0 +1,5 @@ +--- +title: "Rethrow Exception" +linkTitle: "Rethrow Exception" +description: "Rethrow a previously thrown and handled exception." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/rethrow-exception-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/rethrow-exception-block.md new file mode 100644 index 000000000..ce29e032c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/rethrow-exception/rethrow-exception-block.md @@ -0,0 +1,89 @@ +--- +title: "Rethrow Exception" +linkTitle: "Rethrow Exception" +description: "Rethrows an Exception which has previously been thrown and handled." +--- + +{{< figure src="/blocks/exceptions-rethrow-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.RethrowException.RethrowExceptionBlock)
+ +## Description + +Rethrows an [Exception][Exception Property] which has previously been thrown and handled. + +## Examples + +### Rethrowing an Exception + +This example will rethrow the following handled [Exception][] thrown by an [Add Item At Beginning][] block: + +{{< figure src="/images/rethrow-original-list-exception.png" >}} + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Exception][Exception Property] | `($)Exception`, with value of`{"Exception Type": "PropertyNullException","Message": "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this.","HelpLink": "https://docs.wearecortex.com/docs/2023.5/reference/exceptions/common/property/property-null-exception/"}` | `($)Exception` is a variable of type [PropertyNullException][] | + +#### Result + +Rethrowing `($)Exception` results in the [Exception][Exception Property] being rethrown and shown in the [Exceptions Viewer][]: + +{{< figure src="/images/rethrow-from-list-exception.png" >}} + +*** + +## Properties + +### Exception + +The [Exception][Exception Property] that is rethrown. + +[Exception][Exception Property] can be any [Exception data type][Exception]. + +| | | +|--------------------|---------------------------| +| Data Type | [Exception][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Exception` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Exception][Exception Property] is `null`. | + +## Remarks + +### Propagating Exceptions + +Sometimes it is necessary to propagate exceptions thrown in a child flow to the flow that called it. Currently, using the [Rethrow Exception][] block to rethrow the [Exception][] from the [Handle Flow Exception][] workspace is the only way to achieve this. This can be seen below: + +{{< figure src="/images/rethrow-from-subflow.gif" >}} + +In future, additional ways to propagate exceptions between flows may be added. + +[Exception Property]: {{< ref "#exception" >}} + +[Rethrow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.RethrowException.RethrowException.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Add Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemAtBeginning.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Exceptions Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.ExceptionsViewer">}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/_index.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/_index.md new file mode 100644 index 000000000..6825cb935 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/_index.md @@ -0,0 +1,5 @@ +--- +title: "Throw Exception" +linkTitle: "Throw Exception" +description: "Throw an exception." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/throw-new-flow-exception-block.md b/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/throw-new-flow-exception-block.md new file mode 100644 index 000000000..f0d41a4a9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Exceptions/throw-exception/throw-new-flow-exception-block.md @@ -0,0 +1,185 @@ +--- +title: "Throw New Flow Exception" +linkTitle: "Throw New Flow Exception" +description: "Throws a new FlowException with the specified message, category, error code, details, inner exception and help link." +--- + +{{< figure src="/blocks/exceptions-throw-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Exceptions.ThrowException.ThrowNewFlowExceptionBlock)
+ +## Description + +Throws a new [FlowException][] with the specified [Message][Message Property], [Category][Category Property], [Error Code][ErrorCode Property], [Details][Details Property], [Inner Exception][InnerException Property] and [Help Link][HelpLink Property]. + +All properties are optional, and if not supplied will be set to the following default values: + +| Property | Default Value | +|--------------------|-----------------------------------| +| [Message][Message Property] | `"Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown."` | +| [Category][Category Property] | `null` | +| [Error Code][ErrorCode Property] | `null` | +| [Details][Details Property] | `null`| +| [InnerException][InnerException Property] | `null` | +| [HelpLink][HelpLink Property] | `https://docs.wearecortex.com/docs/2023.5/reference/exceptions/flows/flow-exception/` | + +## Examples + +### Throw new FlowException with full configuration + +This example will throw a new [FlowException][] with all properties configured. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Message][Message Property] | `($)Message`, with value `"Custom Message"` | `($)Message` is a variable of type [String][] | +| [Category][Category Property] | `($)Category`, with value `"Custom Category"` | `($)Category` is a variable of type [String][] | +| [Error Code][ErrorCode Property] | `($)ErrorCode`, with value `100` | `($)ErrorCode` is a variable of type [Nullable][]<[Int32][]> | +| [Details][Details Property] | `($)Details`, with value `{"DetailsKey1" : "DetailsValue1", "DetailsKey2" : "DetailsValue2"}` | `($)Details` is a variable of type [IDictionary][]<[String][], [String][]> | +| [InnerException][InnerException Property] | `($)InnerException`, with value `($)Exception` containing another [FlowException][] with default properties | `($)InnerException` is a variable of type [FlowException][] | +| [HelpLink][HelpLink Property] | `($)HelpLink`, with value `"http://customdomain.com/customurl"` | `($)HelpLink` is a variable of type [String][] | + +#### Result + +Throwing a new [FlowException][] with properties configured as above will result in the following exception: + +{{< figure src="/images/flow-exception-full-configuration.png" >}} + +*** + +### Throw new FlowException with no configuration + +This example will throw a new [FlowException][] with no configuration. + +#### Properties + +No properties are configured for this example. + +#### Result + +Throwing a new [FlowException][] without configuring any of the block's properties will result in the following exception: + +{{< figure src="/images/flow-exception-no-configuration.png" >}} + +*** + +## Properties + +### Message + +A [Message][Message Property] describing the exception that occurred. + +If [Message][Message Property] is not provided or is set to `null`, it will default to `"Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown."`. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Category + +A [Category][Category Property] that can be used to categorise similar types of exception that has occurred (e.g. an `AuthenticationError` category may be set for exceptions relating to authentication issues). This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Error Code + +An [Error Code][ErrorCode Property] that can be used to uniquely identify the type of exception (e.g. There may be multiple exceptions with the same `AuthenticationError` category set, such as `InvalidCredentials`, `TokenExpired`. In this case each exception can be assigned its own unique [Error Code][ErrorCode Property]; `InvalidCredentials` = `100` and `TokenExpired` = `101`). This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting. + +If [Error Code][ErrorCode Property] is not provided, it will default to `null`. + +| | | +|--------------------|---------------------------| +| Data Type | [Nullable][]<[Int32][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Details + +[Details][Details Property] can be used to provide more detailed information about the exception. It can be any type of [Object][]. This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Inner Exception + +[Inner Exception][InnerException Property] can be used to include another [exception][] within the thrown exception (e.g. If the [FlowException][] has been thrown as a result of handling another [exception][], then the handled [exception][] can be included within the [FlowException][] to add traceability). + +| | | +|--------------------|---------------------------| +| Data Type | [Exception][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Help Link + +A [Help Link][HelpLink Property] can be specified where further information can be found about the exception being thrown. + +If [Help Link][HelpLink Property] is not provided or is set to `null`, it will default to a link to the [FlowException][] page; please note this page will not provide any guidance on how to fix the solution specific [exception][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null Message + +If [Message][Message Property] is not provided or is set to `null`, it will default to `"Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown."`. + +### Null Help Link + +If [Help Link][HelpLink Property] is not provided or is set to `null`, it will default to a link to the [FlowException][] page, please note this page will not provide any guidance on how to fix the solution specific [exception][]. + +[Message Property]: {{< ref "#message" >}} +[Category Property]: {{< ref "#category" >}} +[ErrorCode Property]: {{< ref "#error-code" >}} +[Details Property]: {{< ref "#details" >}} +[InnerException Property]: {{< ref "#inner-exception" >}} +[HelpLink Property]: {{< ref "#help-link" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[FlowException]: {{< url path="Cortex.Reference.Exceptions.Flows.FlowException.MainDoc" >}} +[Nullable]: {{< url path="Cortex.Reference.DataTypes.Other.Nullable.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/_index.md new file mode 100644 index 000000000..f42a0941a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/_index.md @@ -0,0 +1,5 @@ +--- +title: "Files & Folders" +linkTitle: "Files & Folders" +description: "Blocks related to working with Files and Folders." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/_index.md new file mode 100644 index 000000000..e5fb6edbb --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Check File Exists" +linkTitle: "Check File Exists" +description: "Check if a file exists." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/check-file-exists-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/check-file-exists-block.md new file mode 100644 index 000000000..4941c1b87 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-file/check-file-exists-block.md @@ -0,0 +1,159 @@ +--- +title: "Check File Exists" +linkTitle: "Check File Exists" +description: "Checks if a file exists at the specified file path." +--- + +{{< figure src="/blocks/files-check-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CheckFile.CheckFileExistsBlock)
+ +## Description + +Checks if a [File Exists][FileExists Property] at the specified [File Path][FilePath Property]. + +## Examples + +### File exists at the specified File Path + +This example will check if `"C:\Windows\System32\cmd.exe"` exists on the Windows server executing the flow. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Windows\System32\cmd.exe"` | `($)FilePath` is a variable of type [String][] | +| [File Exists][FileExists Property] | `($)FileExists`, with no value | `($)FileExists` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"C:\Windows\System32\cmd.exe"` is the command prompt application on Windows machines. Checking this on the Windows server executing the flow will result in the variable `($)FileExists` being updated to the following: + +```json +true +``` + +*** + +### File does not exist at the specified File Path + +This example will check if `"/etc/passwd"` exists on the Windows server executing the flow. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `"/etc/passwd"` | `($)FilePath` is a variable of type [String][] | +| [File Exists][FileExists Property] | `($)FileExists`, with no value | `($)FileExists` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"/etc/passwd"` is a file that exists on Linux machines containing the list of system accounts. Checking this on the Windows server executing the flow will result in the variable `($)FileExists` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to check a file exists at. + +The [File Path][FilePath Property] is case-insensitive, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### File Exists + +The result of the file exists check. + +If the file exists at the specified [File Path][FilePath Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FileExists` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Windows\\System32\\cmd.exe"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Windows\System32\cmd.exe"`) + +### Null File Path + +If [File Path][FilePath Property] is `null` the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +### Empty File Path + +If [File Path][FilePath Property] is empty (i.e. `""`) the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +### Invalid File Path + +If [File Path][FilePath Property] is invalid (i.e. contains any of the following characters: `"`, `*`, `?`, `|`, `<`, `>`, `:`, `\`, `/`) the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +### File Path points to a folder + +If [File Path][FilePath Property] points to a folder, the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +To check if a folder exists, use the [Check Folder Exists block][]. + +### File Path contains leading spaces + +If [File Path][FilePath Property] contains leading spaces they are not removed; however, trailing spaces are removed. + +### Error occurs whilst checking if the file exists + +If any error occurs whilst checking if a file exists at the specified [File Path][FilePath Property], the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +### User does not have necessary permissions to check if the file exists + +If the user the flow is executing as does not have permissions to check if a file exists at the specified [File Path][FilePath Property], the variable specified in the [File Exists][FileExists Property] property will be set to `false`. + +[FilePath Property]: {{< ref "#file-path" >}} +[FileExists Property]: {{< ref "#file-exists" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Check Folder Exists block]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CheckFolder.CheckFolderExists.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/_index.md new file mode 100644 index 000000000..4ae62e559 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Check Folder Exists" +linkTitle: "Check Folder Exists" +description: "Check if a folder exists." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/check-folder-exists-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/check-folder-exists-block.md new file mode 100644 index 000000000..3e2d5062a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/check-folder/check-folder-exists-block.md @@ -0,0 +1,159 @@ +--- +title: "Check Folder Exists" +linkTitle: "Check Folder Exists" +description: "Checks if a folder exists at the specified folder path." +--- + +{{< figure src="/blocks/folders-check-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CheckFolder.CheckFolderExistsBlock)
+ +## Description + +Checks if a [Folder Exists][FolderExists Property] at the specified [Folder Path][FolderPath Property]. + +## Examples + +### Folder exists at the specified Folder Path + +This example will check if `"C:\Windows\System32"` exists on the Windows server executing the flow. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Windows\System32"` | `($)FolderPath` is a variable of type [String][] | +| [Folder Exists][FolderExists Property] | `($)FolderExists`, with no value | `($)FolderExists` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"C:\Windows\System32"` is the folder on Windows machines that contains files critical to the functioning of the operating system. Checking this on the Windows server executing the flow will result in the variable `($)FolderExists` being updated to the following: + +```json +true +``` + +*** + +### Folder does not exist at the specified Folder Path + +This example will check if `"/etc"` exists on the Windows server executing the flow. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `"/etc"` | `($)FolderPath` is a variable of type [String][] | +| [Folder Exists][FolderExists Property] | `($)FolderExists`, with no value | `($)FolderExists` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"/etc"` is the folder on Linux machines containing system configuration files. Checking this on the Windows server executing the flow will result in the variable `($)FolderExists` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to check a folder exists at. + +The [Folder Path][FolderPath Property] is case-insensitive, any trailing spaces will be automatically removed, and can end with or without a trailing `\` (e.g. `@"C:\Windows\System32"` or `@"C:\Windows\System32\"`). + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Folder Exists + +The result of the folder exists check. + +If the folder exists at the specified [Folder Path][FolderPath Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderExists` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Windows\\System32"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Windows\System32"`) + +### Null Folder Path + +If [Folder Path][FolderPath Property] is `null` the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +### Empty Folder Path + +If [Folder Path][FolderPath Property] is empty (i.e. `""`) the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +### Invalid Folder Path + +If [Folder Path][FolderPath Property] is invalid (i.e. contains any of the following characters: `"`, `*`, `?`, `|`, `<`, `>`, `:`, `\`, `/`) the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +### Folder Path points to a file + +If [Folder Path][FolderPath Property] points to a file, the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +To check if a file exists, use the [Check File Exists block][]. + +### Folder Path contains leading spaces + +If [Folder Path][FolderPath Property] contains leading spaces they are not removed; however, trailing spaces are removed. + +### Error occurs whilst checking if the folder exists + +If any error occurs whilst checking if a folder exists at the specified [Folder Path][FolderPath Property], the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +### User does not have necessary permissions to check if the folder exists + +If the user the flow is executing as does not have permissions to check if a folder exists at the specified [Folder Path][FolderPath Property], the variable specified in the [Folder Exists][FolderExists Property] property will be set to `false`. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[FolderExists Property]: {{< ref "#folder-exists" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Check File Exists block]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CheckFile.CheckFileExists.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/_index.md new file mode 100644 index 000000000..71e54f21e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Copy File(s)" +linkTitle: "Copy File(s)" +description: "Copy a file or multiple files." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-file-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-file-block.md new file mode 100644 index 000000000..11b1d51df --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-file-block.md @@ -0,0 +1,224 @@ +--- +title: "Copy File" +linkTitle: "Copy File" +description: "Copies a file at the specified file path to the given destination path." +--- + +{{< figure src="/blocks/files-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CopyFile.CopyFileBlock)
+ +## Description + +Copies a file at the specified [File Path][FilePath Property] to the given [Destination Path][DestinationPath Property], with an option to [Overwrite][Overwrite Property] the file if it already exists. + +## Examples + +### Copy a file to a folder keeping the same file name + +This example will copy `"C:\Source\OriginalFile.txt"` to `"C:\Destination"`, with the same file name of `"OriginalFile.txt"`. + +In this example assume `"C:\Destination"` does not already contain a file named `"OriginalFile.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\OriginalFile.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\OriginalFile.txt"` to `"C:\Destination"` that does not already contain a file named `"OriginalFile.txt"` will: + +* Create a new file at `"C:\Destination\OriginalFile.txt"` with: + * The content copied from `"C:\Source\OriginalFile.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\OriginalFile.txt"`. + * The [File Attributes][] copied from `"C:\Source\OriginalFile.txt"`. + +*** + +### Copy a file to a folder with a new name + +This example will copy `"C:\Source\OriginalFile.txt"` to `"C:\Destination"`, with a new file name of `"NewFile.txt"`. + +To rename the file when it is being copied, please note that the [Destination Path][DestinationPath Property] must be a file path, rather than a folder path (e.g. `"C:\Destination\NewFile.txt"` rather than `"C:\Destination"`). + +In this example assume `"C:\Destination"` does not already contain a file named `"NewFile.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\OriginalFile.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination\NewFile.txt"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\OriginalFile.txt"` to the path `"C:\Destination\NewFile.txt"` that does not already exist will: + +* Create a new file at `"C:\Destination\NewFile.txt"` with: + * The content copied from `"C:\Source\OriginalFile.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\OriginalFile.txt"`. + * The [File Attributes][] copied from `"C:\Source\OriginalFile.txt"`. + +*** + +### Copy a file to a folder overwriting any file that already exists with the same name + +This example will copy `"C:\Source\FileAlreadyExists.txt"` to `"C:\Destination"`, with the same file name of `"FileAlreadyExists.txt"`. + +In this example assume `"C:\Destination"` already contains a file named `"FileAlreadyExists.txt"`, so overwrite must be set to `true` to ensure the content of the existing file can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\FileAlreadyExists.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\FileAlreadyExists.txt"` to `"C:\Destination"` and overwriting the existing file named `"FileAlreadyExists.txt"` will: + +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists.txt"`. + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to copy the file from. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to copy the file to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] can either point to a folder or a file: + +* If it points to a folder, the copied file will have the name specified in the [File Path][FilePath Property]. +* If it points to a file, the copied file will have the name specified in the [Destination Path][DestinationPath Property]. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the file in the [Destination Path][DestinationPath Property] if it already exists. + +If the file exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [Destination Path][DestinationPath Property] (if it points to a file), or the [Destination Path][DestinationPath Property] (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [File Path][FilePath Property] does not exist. | +| | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | The file in the specified [Destination Path][DestinationPath Property] exists and overwrite is `false`. | +| | The file in the specified [Destination Path][DestinationPath Property] exists, is read-only and overwrite is `true`. | +| | The file in the specified [Destination Path][DestinationPath Property] exists, is hidden and overwrite is `true`, but the file in the specified [File Path][FilePath Property] is not hidden.| +| | The user the flow is executing as does not have the required permissions to copy the file (e.g. not having read access to the [File Path][FilePath Property] or write access to the [Destination Path][DestinationPath Property]). | +| | An unexpected error occurs when copying the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### File and Folder Paths + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path and Destination Path need escaping + +[File Path][FilePath Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\OriginalFile.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\OriginalFile.txt"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### File Attributes + +When copying a file from the [File Path][FilePath Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes will also be copied. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +[FilePath Property]: {{< ref "#file-path" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} + +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md new file mode 100644 index 000000000..5d6b42de9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md @@ -0,0 +1,217 @@ +--- +title: "Copy Files" +linkTitle: "Copy Files" +description: "Copies files at the specified file paths to the given destination path." +--- + +{{< figure src="/blocks/files-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CopyFile.CopyFilesBlock)
+ +## Description + +Copies files at the specified [File Paths][FilePaths Property] to the given [Destination Path][DestinationPath Property], with an option to [Overwrite][Overwrite Property] the files if they already exist. + +## Examples + +### Copy files to a folder keeping the same file names + +This example will copy `["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"]` to `"C:\Destination"`, with the same file names of `"OriginalFile1.txt"` and `"OriginalFile2.txt"`. + +In this example assume `"C:\Destination"` does not already contain a file named `"OriginalFile1.txt"` or a file named `"OriginalFile2.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\OriginalFile1.txt", @"C:\Source\OriginalFile2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"]` to `"C:\Destination"` that does not already contain files named `"OriginalFile1.txt"` and `"OriginalFile2.txt"` will: + +* Create a new file at `"C:\Destination\OriginalFile1.txt"` with: + * The content copied from `"C:\Source\OriginalFile1.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\OriginalFile1.txt"`. + * The [File Attributes][] copied from `"C:\Source\OriginalFile1.txt"`. +* Create a new file at `"C:\Destination\OriginalFile2.txt"` with: + * The content copied from `"C:\Source\OriginalFile2.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\OriginalFile2.txt"`. + * The [File Attributes][] copied from `"C:\Source\OriginalFile2.txt"`. + +*** + +### Copy files to a folder overwriting any files that already exists with the same names + +This example will copy `["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"]` to `"C:\Destination"`, with the same file names of `"FileAlreadyExists1.txt"` and `"FileAlreadyExists2.txt"`. + +In this example assume `"C:\Destination"` already contains a file named `"FileAlreadyExists1.txt"` and a file named `"FileAlreadyExists2.txt"`, so overwrite must be set to `true` to ensure the content of the existing files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\FileAlreadyExists1.txt", @"C:\Source\FileAlreadyExists2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"]` to `"C:\Destination"` and overwriting the existing files named `"FileAlreadyExists1.txt"` and `"FileAlreadyExists2.txt"` will: + +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists1.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists1.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists1.txt"`. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists2.txt"`. + +*** + +## Properties + +### File Paths + +The [File Paths][FilePaths Property] to copy the files from. + +Each file path in [File Paths][FilePaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePaths` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to copy the files to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The copied files will have the names specified in the [File Paths][FilePaths Property]. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the files in the [Destination Path][DestinationPath Property] if they already exist. + +If any file exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] does not point to a folder. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [Destination Path][DestinationPath Property] (if it points to a file), or the [Destination Path][DestinationPath Property] (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | Any file path in [File Paths][FilePaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty File Paths][]| +| | Any file path in [File Paths][FilePaths Property] is duplicated. For more information, see [Duplicate File Paths][] | +| | Any file path in [File Paths][FilePaths Property] does not exist. | +| | Any file path in [File Paths][FilePaths Property] points to a folder. | +| | Any file path in [File Paths][FilePaths Property] contains leading spaces. | +| | Any file path in [File Paths][FilePaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | Any file path in [File Paths][FilePaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any file path in [File Paths][FilePaths Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | Any file path in [File Paths][FilePaths Property] exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file path in [File Paths][FilePaths Property] exists in the specified [Destination Path][DestinationPath Property] with the same name, is read-only and overwrite is `true`. | +| | Any file path in [File Paths][FilePaths Property] exists in the specified [Destination Path][DestinationPath Property] with the same name, is hidden and overwrite is `true`, but the file in the specified [File Paths][FilePaths Property] is not hidden.| +| | The user the flow is executing as does not have the required permissions to copy any file (e.g. not having read access to a file path in [File Paths][FilePaths Property] or write access to the [Destination Path][DestinationPath Property]). | +| | An unexpected error occurs when copying a file. | +| [PropertyEmptyException][] | Thrown when [File Paths][FilePaths Property] does not contain any items, or [Destination Path][DestinationPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Paths][FilePaths Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### File and Folder Paths + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Paths and Destination Path need escaping + +Each file path in [File Paths][FilePaths Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\OriginalFile.txt"`), or +* Prepending an `@` character before the start of the +file path (e.g. `@"C:\Source\OriginalFile.txt"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### File Attributes + +When copying a file in the [File Paths][FilePaths Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes will also be copied. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Handling of Exceptions + +If an exception occurs when trying to copy a file in the [File Paths][FilePaths Property], it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FilePaths Property]: {{< ref "#file-paths" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} + +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/_index.md new file mode 100644 index 000000000..0b4717a91 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Copy Folder(s)" +linkTitle: "Copy Folder(s)" +description: "Copy a folder or multiple folders." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folder-block.md new file mode 100644 index 000000000..4b13ef407 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folder-block.md @@ -0,0 +1,386 @@ +--- +title: "Copy Folder" +linkTitle: "Copy Folder" +description: "Copies a folder at the specified folder path to the given destination path." +--- + +{{< figure src="/blocks/folders-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CopyFolder.CopyFolderBlock)
+ +## Description + +Copies a folder at the specified [Folder Path][FolderPath Property] to the given [Destination Path][DestinationPath Property], with an option to copy the folder and its content, or just its [Content Only][ContentOnly Property]. + +An option can also be specified to [Overwrite][Overwrite Property] anything being copied that already exists in the [Destination Path][DestinationPath Property]. + +## Examples + +### Copy a folder and its content + +This example will copy `"C:\Source\Folder"` and its content to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. +* `"C:\Destination"` does not already contain a folder named `"Folder"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\Folder"` and its content to `"C:\Destination"` that does not already contain a folder named `"Folder"` will: + +* Create a new folder at `"C:\Destination\Folder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder"`. +* Create a new folder at `"C:\Destination\Folder\SubFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder\SubFolder"`. +* Create a new file at `"C:\Destination\Folder\File.txt"` with: + * The content copied from `"C:\Source\Folder\File.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\File.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\File.txt"`. + +*** + +### Copy a folder and its content, overwriting any content that already exists + +This example will copy `"C:\Source\Folder"` and its content to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * An empty sub-folder named `"SubFolderAlreadyExists"`. + * A file named `"File.txt"`. + * A file named `"FileAlreadyExists.txt"`. +* `"C:\Destination"` already contains a folder named `"Folder"`, which already contains: + * A folder named `"SubFolderAlreadyExists"`. + * A file named `"FileAlreadyExists.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing `"SubFolderAlreadyExists"` and `"FileAlreadyExists.txt"` can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\Folder"` and its content to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\Folder"`, `"C:\Destination\Folder\SubFolderAlreadyExists"` and `"C:\Destination\Folder\FileAlreadyExists.txt"` already exist will: + +* Overwrite the existing folder at `"C:\Destination\Folder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new empty folder at `"C:\Destination\Folder\SubFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder\SubFolder"`. +* Overwrite the existing folder at `"C:\Destination\Folder\SubFolderAlreadyExists"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\Folder\File.txt"` with: + * The content copied from `"C:\Source\Folder\File.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\File.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\File.txt"`. +* Overwrite the existing file at `"C:\Destination\Folder\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + +*** + +### Copy a folder's content only + +This example will copy `"C:\Source\Folder"` content only to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. +* `"C:\Destination"` does not already contain a folder named `"SubFolder"` or a file named `"File.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\Folder"` content only to `"C:\Destination"` that does not already contain a folder named `"SubFolder"` or a file named `"File.txt"` will: + +* Create a new folder at `"C:\Destination\SubFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder\SubFolder"`. +* Create a new file at `"C:\Destination\File.txt"` with: + * The content copied from `"C:\Source\Folder\File.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\File.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\File.txt"`. + +*** + +### Copy a folder's content only, overwriting any content that already exists + +This example will copy `"C:\Source\Folder"` content only to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * An empty sub-folder named `"SubFolderAlreadyExists"`. + * A file named `"File.txt"`. + * A file named `"FileAlreadyExists.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"SubFolderAlreadyExists"`. + * A file named `"FileAlreadyExists.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing `"SubFolderAlreadyExists"` and `"FileAlreadyExists.txt"` can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `"C:\Source\Folder"` content only to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\SubFolderAlreadyExists"` and `"C:\Destination\FileAlreadyExists.txt"` already exist will: + +* Create a new empty folder at `"C:\Destination\SubFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder\SubFolder"`. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\File.txt"` with: + * The content copied from `"C:\Source\Folder\File.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\File.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\File.txt"`. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + +*** + +### Copy a folder and its content to the same location but with a different name + +If it is required to copy a folder and its content into the same folder it is currently located in, but with a different name, then it is not possible to do with this block; the [Duplicate Folder][] block must be used instead. + +*** + +### Copy a folder and its content to a different location but with a different name + +If it is required to copy a folder and its content into a different folder than the one it is currently located in, but with a different name, then it is not possible to do with this block; the [Rename Folder][] block must be used instead. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to copy the folder and/or its content from. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to copy the folder and/or its content to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The copied folders and files will have the same names as the folders and files copied. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the folder and/or contents being copied to in the [Destination Path][DestinationPath Property] if they already exist. + +If the folder and/or contents exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing folders and files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Content Only + +Option to specify whether to copy the folder and its content or just the [Content Only][ContentOnly Property]. + +To copy the folder and its content, [Content Only][ContentOnly Property] must be set to `false`; to copy just the content, [Content Only][ContentOnly Property] must be set to `true`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] points to a file. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Destination Path][DestinationPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [Folder Path][FolderPath Property] does not exist. | +| | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | The [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | The [Folder Path][FolderPath Property] and [Destination Path][DestinationPath Property] point to the same folder and [Content Only][ContentOnly Property] is `true`. | +| | The [Folder Path][FolderPath Property] is a child folder in the [Destination Path][DestinationPath Property] and [Content Only][ContentOnly Property] is `false`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property], is read-only and overwrite is `true`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property], is hidden and overwrite is `true`, but the file under the specified [Folder Path][FolderPath Property] is not hidden.| +| | The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to the [Folder Path][FolderPath Property] or its content, or write access to the [Destination Path][DestinationPath Property]). | +| | The operation is cyclic (e.g. copying a folder into one of its sub-folders). | +| | An unexpected error occurs when copying the folder or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path and Destination Path need escaping + +[Folder Path][FolderPath Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### Folder Attributes + +When copying the folder at the specified [Folder Path][FolderPath Property] or any folder under it to the new [Destination Path][DestinationPath Property], if the copied folder already exists its attributes remain unchanged, otherwise they are copied. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### File Attributes + +When copying a file under [Folder Path][FolderPath Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes are also copied. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Handling of Exceptions + +If an exception occurs when trying to copy [Folder Path][FolderPath Property], an [OperationFailedException][] will be thrown. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[ContentOnly Property]: {{< ref "#content-only" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.MainDoc" >}} +[Duplicate Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.DuplicateFolder.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md new file mode 100644 index 000000000..4c28f4f99 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md @@ -0,0 +1,498 @@ +--- +title: "Copy Folders" +linkTitle: "Copy Folders" +description: "Copies folders at the specified folder paths to the given destination path." +--- + +{{< figure src="/blocks/folders-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CopyFolder.CopyFoldersBlock)
+ +## Description + +Copies folders at the specified [Folder Paths][FolderPaths Property] to the given [Destination Path][DestinationPath Property], with an option to copy the folders and their content, or just their [Content Only][ContentOnly Property]. + +An option can also be specified to [Overwrite][Overwrite Property] anything being copied that already exists in the [Destination Path][DestinationPath Property]. + +## Examples + +### Copy folders and their content + +This example will copy `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * A file named `"File1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * A file named `"File2.txt"`. +* `"C:\Destination"` does not already contain a folder named `"Folder1"` or `"Folder2"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"` that does not already contain folders named `"Folder1"` and `"Folder2"` will: + +* Create a new folder at `"C:\Destination\Folder1"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder1"`. +* Create a new folder at `"C:\Destination\Folder1\SubFolder1"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder1\SubFolder1"`. +* Create a new file at `"C:\Destination\Folder1\File1.txt"` with: + * The content copied from `"C:\Source\Folder1\File1.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\File1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\File1.txt"`. +* Create a new folder at `"C:\Destination\Folder2"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder2"`. +* Create a new folder at `"C:\Destination\Folder2\SubFolder2"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder2\SubFolder2"`. +* Create a new file at `"C:\Destination\Folder2\File2.txt"` with: + * The content copied from `"C:\Source\Folder2\File2.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\File2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\File2.txt"`. + +*** + +### Copy folders and their content, overwriting any content that already exists + +This example will copy `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * An empty sub-folder named `"SubFolderAlreadyExists1"`. + * A file named `"File1.txt"`. + * A file named `"FileAlreadyExists1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * An empty sub-folder named `"SubFolderAlreadyExists2"`. + * A file named `"File2.txt"`. + * A file named `"FileAlreadyExists2.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"Folder1"`, which already contains: + * A folder named `"SubFolderAlreadyExists1"`. + * A file named `"FileAlreadyExists1.txt"`. + * A folder named `"Folder2"`, which already contains: + * A folder named `"SubFolderAlreadyExists2"`. + * A file named `"FileAlreadyExists2.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing folders and files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\Folder1"`, `"C:\Destination\Folder1\SubFolderAlreadyExists1"`, `"C:\Destination\Folder1\FileAlreadyExists1.txt"`, `"C:\Destination\Folder2"`, `"C:\Destination\Folder2\SubFolderAlreadyExists2"` and `"C:\Destination\Folder2\FileAlreadyExists2.txt"` already exist will: + +* Overwrite the existing folder at `"C:\Destination\Folder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new empty folder at `"C:\Destination\Folder1\SubFolder1"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder1\SubFolder1"`. +* Overwrite the existing folder at `"C:\Destination\Folder1\SubFolderAlreadyExists1"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\Folder1\File1.txt"` with: + * The content copied from `"C:\Source\Folder1\File1.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\File1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\File1.txt"`. +* Overwrite the existing file at `"C:\Destination\Folder1\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. +* Overwrite the existing folder at `"C:\Destination\Folder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new empty folder at `"C:\Destination\Folder2\SubFolder2"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder2\SubFolder2"`. +* Overwrite the existing folder at `"C:\Destination\Folder2\SubFolderAlreadyExists2"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\Folder2\File2.txt"` with: + * The content copied from `"C:\Source\Folder2\File2.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\File2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\File2.txt"`. +* Overwrite the existing file at `"C:\Destination\Folder2\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + +*** + +### Copy the folders' content only + +This example will copy `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * A file named `"File1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * A file named `"File2.txt"`. +* `"C:\Destination"` does not already contain a folder named `"SubFolder1"` or `"SubFolder2"` or a file named `"File1.txt"` or `"File2.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"` that does not already contain a folder named `"SubFolder1"` or `"SubFolder2"` or a file named `"File1.txt"` or `"File2.txt"` will: + +* Create a new folder at `"C:\Destination\SubFolder1"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder1\SubFolder1"`. +* Create a new file at `"C:\Destination\File1.txt"` with: + * The content copied from `"C:\Source\Folder1\File1.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\File1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\File1.txt"`. +* Create a new folder at `"C:\Destination\SubFolder2"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder2\SubFolder2"`. +* Create a new file at `"C:\Destination\File2.txt"` with: + * The content copied from `"C:\Source\Folder2\File2.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\File2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\File2.txt"`. + +*** + +### Copy folders' content only, overwriting any content that already exists + +This example will copy `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * An empty sub-folder named `"SubFolderAlreadyExists1"`. + * A file named `"File1.txt"`. + * A file named `"FileAlreadyExists1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * An empty sub-folder named `"SubFolderAlreadyExists2"`. + * A file named `"File2.txt"`. + * A file named `"FileAlreadyExists2.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"SubFolderAlreadyExists1"`. + * A folder named `"SubFolderAlreadyExists2"`. + * A file named `"FileAlreadyExists1.txt"`. + * A file named `"FileAlreadyExists2.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing folders and files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Copying `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\SubFolderAlreadyExists1"`, `"C:\Destination\SubFolderAlreadyExists2"`, `"C:\Destination\FileAlreadyExists1.txt"` and `"C:\Destination\FileAlreadyExists2.txt"` already exist will: + +* Create a new empty folder at `"C:\Destination\SubFolder1"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder1\SubFolder1"`. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists1"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\File1.txt"` with: + * The content copied from `"C:\Source\Folder1\File1.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\File1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\File1.txt"`. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. +* Create a new empty folder at `"C:\Destination\SubFolder2"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder2\SubFolder2"`. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists2"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Create a new file at `"C:\Destination\File2.txt"` with: + * The content copied from `"C:\Source\Folder2\File2.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\File2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\File2.txt"`. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + +*** + +### Copy folders and their content to the same location but with a different name + +If it is required to copy folders and their content into the same folder they are currently located in, but with a different name, then it is not possible to do with this block; the [Duplicate Folder][] block must be used instead. + +*** + +### Copy folders and their content to a different location but with a different name + +If it is required to copy folders and their content into a different folder than the one they are currently located in, but with a different name, then it is not possible to do with this block; the [Rename Folder][] block must be used instead. + +*** + +## Properties + +### Folder Paths + +The [Folder Paths][FolderPaths Property] to copy the folders and/or their content from. + +Each folder path in [Folder Paths][FolderPaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPaths` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to copy the folders and/or their content to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The copied folders and files will have the same names as the folders and files copied. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the folders and/or contents being copied to in the [Destination Path][DestinationPath Property] if they already exist. + +If any of the folders and/or contents exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing folders and files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Content Only + +Option to specify whether to copy the folders and their content or just the [Content Only][ContentOnly Property]. + +To copy the folders and their content, [Content Only][ContentOnly Property] must be set to `false`; to copy just the content, [Content Only][ContentOnly Property] must be set to `true`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] points to a file. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Destination Path][DestinationPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | Any folder path in [Folder Paths][FolderPaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty Folder Paths][]| +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. For more information, see [Duplicate Folder Paths][] | +| | Any folder path in [Folder Paths][FolderPaths Property] does not exist. | +| | Any folder path in [Folder Paths][FolderPaths Property] points to a file. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains leading spaces. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | Any folder path in [Folder Paths][FolderPaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any folder path in [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | Any folder path in [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | Any folder path in [Folder Paths][FolderPaths Property] and [Destination Path][DestinationPath Property] point to the same folder and [Content Only][ContentOnly Property] is `true`. | +| | Any folder path in [Folder Paths][FolderPaths Property] is a child folder in the [Destination Path][DestinationPath Property] and [Content Only][ContentOnly Property] is `false`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property], is read-only and overwrite is `true`. | +| | Any file being copied already exists in the specified [Destination Path][DestinationPath Property], is hidden and overwrite is `true`, but the file under any of the specified [Folder Paths][FolderPaths Property] is not hidden.| +| | The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to any of the folders in [Folder Paths][FolderPaths Property] or its content, or write access to the [Destination Path][DestinationPath Property]). | +| | The operation is cyclic (e.g. copying a folder into one of its sub-folders). | +| | An unexpected error occurs when copying a folder or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Paths][FolderPaths Property] does not contain any items, or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path and Destination Path need escaping + +Each folder paths in [Folder Paths][FolderPaths Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the folder path (e.g. `@"C:\Source"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### Folder Attributes + +When copying the folders at the specified [Folder Paths][FolderPaths Property] or any folder under them to the new [Destination Path][DestinationPath Property], if the copied folder already exists its attributes remain unchanged, otherwise they are copied. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### File Attributes + +When copying a file under any of the [Folder Paths][FolderPaths Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes are also copied. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Conflicting Content + +If two or more paths in the specified [Folder Paths][FolderPaths Property] contain content (folders or files) with the same name, and [Overwrite][Overwrite Property] and [Content Only][ContentOnly Property] are `true`: + +* The attributes of the folder/file in the [Destination Path][DestinationPath Property] will be that of the first one copied. +* For files, the content of the file in the [Destination Path][DestinationPath Property] will be that of the last one copied. + +### Handling of Exceptions + +If an exception occurs when trying to copy a folder in [Folder Paths][FolderPaths Property], it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FolderPaths Property]: {{< ref "#folder-paths" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[ContentOnly Property]: {{< ref "#content-only" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.MainDoc" >}} +[Duplicate Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.DuplicateFolder.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/duplicate-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/duplicate-folder-block.md new file mode 100644 index 000000000..f529ee099 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/copy-folder/duplicate-folder-block.md @@ -0,0 +1,181 @@ +--- +title: "Duplicate Folder" +linkTitle: "Duplicate Folder" +description: "Copies a folder at the specified folder path to the same location but with a new name." +--- + +{{< figure src="/blocks/folders-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CopyFolder.DuplicateFolderBlock)
+ +## Description + +Copies a folder at the specified [Folder Path][FolderPath Property] to the same location but with a [New Name][NewName Property]. + +## Examples + +### Duplicate a folder + +This example will make a copy of `"C:\Source\Folder"` at `"C:\Source\CopyOfFolder"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [New Name][NewName Property] | `($)NewName`, with value `"CopyOfFolder"` | `($)NewName` is a variable of type [String][] | + +#### Result + +Making a copy of `"C:\Source\Folder"` with a new name of `"CopyOfFolder"` will: + +* Create a new folder at `"C:\Source\CopyOfFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder"`. +* Create a new folder at `"C:\Source\CopyOfFolder\SubFolder"` with: + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` set to the time the copy occurred. + * The [Folder attributes][] copied from `"C:\Source\Folder\SubFolder"`. +* Create a new file at `"C:\Source\CopyOfFolder\File.txt"` with: + * The content copied from `"C:\Source\Folder\File.txt"`. + * The `Date Created` set to the time the copy occurred. + * The `Date Accessed` set to the time the copy occurred. + * The `Date Modified` copied from `"C:\Source\Folder\File.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\File.txt"`. + +*** + +### Other Copy Operations + +If any other folder copying operation is required, the [Copy Folder][] or [Copy Folders][] blocks must be used instead. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to copy the folder and its content from. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### New Name + +The [New Name][NewName Property] to use for the copy of the folder. + +The [New Name][NewName Property] is case-insensitive and any trailing spaces will be automatically removed. + +The [New Name][NewName Property] must be a valid folder name, otherwise an [InvalidFolderNameException][] will be thrown. + +All child folders and files copied will have the same names as the folders and files copied. + +For information about valid folder names, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidFolderNameException][] | A folder or file with the [New Name][NewName Property] already exists. | +| | The [New Name][NewName Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`). | +| | The [New Name][NewName Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [Folder Path][FolderPath Property] does not exist. | +| | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | The [Folder Path][FolderPath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to the [Folder Path][FolderPath Property] or its content, or write access to the parent of [Folder Path][FolderPath Property]. | +| | An unexpected error occurs when copying the folder or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] or [New Name][NewName Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] or [New Name][NewName Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +### Folder Attributes + +When copying the folder at or any folder under the specified [Folder Path][FolderPath Property] all of the folder's attributes are also copied. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### File Attributes + +When copying a file under [Folder Path][FolderPath Property] all of the file's attributes are also copied. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Handling of Exceptions + +If an exception occurs when trying to copy [Folder Path][FolderPath Property], an [OperationFailedException][] will be thrown. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[NewName Property]: {{< ref "#new-name" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidFolderNameException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidFolderNameException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Copy Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolder.MainDoc" >}} +[Copy Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolders.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/_index.md new file mode 100644 index 000000000..91e4e4279 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Create Folder(s)" +linkTitle: "Create Folder(s)" +description: "Create a folder or multiple folders." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folder-block.md new file mode 100644 index 000000000..15d450a33 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folder-block.md @@ -0,0 +1,108 @@ +--- +title: "Create Folder" +linkTitle: "Create Folder" +description: "Creates a folder at the specified folder path." +--- + +{{< figure src="/blocks/folders-create-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CreateFolder.CreateFolderBlock)
+ +## Description + +Creates a folder at the specified [Folder Path][FolderPath Property]. + +## Examples + +### Create a folder + +This example will create `"C:\Source\NewFolder"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\NewFolder"` | `($)FolderPath` is a variable of type [String][] | + +#### Result + +Creating `"C:\Source\NewFolder"` results in the folder `"NewFolder"` being created in the folder `"C:\Source"`. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to create the folder at. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +Any folders that do not exist in the [Folder Path][FolderPath Property] will be created. + +If the [Folder Path][FolderPath Property] already exists, a new folder is not created, and no exception is thrown. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to create the folder at the [Folder Path][FolderPath Property]. | +| | An unexpected error occurs when creating the folder at the [Folder Path][FolderPath Property] or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] is `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +### Folder Path already exists + +If the [Folder Path][FolderPath Property] already exists nothing is created, and no exception is thrown. + +[FolderPath Property]: {{< ref "#folder-path" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md new file mode 100644 index 000000000..f7e631cfb --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md @@ -0,0 +1,117 @@ +--- +title: "Create Folders" +linkTitle: "Create Folders" +description: "Create folders at the specified folder paths." +--- + +{{< figure src="/blocks/folders-create-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.CreateFolder.CreateFoldersBlock)
+ +## Description + +Creates folders at the specified [Folder Paths][FolderPaths Property]. + +## Examples + +### Create folders + +This example will create `["C:\Source\NewFolder1", "C:\Source\NewFolder2"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\NewFolder1", @"C:\Source\NewFolder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Creating `["C:\Source\NewFolder1", "C:\Source\NewFolder2"]` results in the folders `"NewFolder1"` and `"NewFolder2"` being create in the folder `"C:\Source"`. + +*** + +## Properties + +### Folder Paths + +The [Folder Paths][FolderPaths Property] to create the folders at. + +Each folder path in [Folder Paths][FolderPaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +Any folders that do not exist in any of the [Folder Paths][FolderPaths Property] will be created. + +If a folder in [Folder Paths][FolderPaths Property] already exists, a new folder is not created, and no exception is thrown. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPaths` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | Any folder path in [Folder Paths][FolderPaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty Folder Paths][]. | +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. For more information, see [Duplicate Folder Paths][]. | +| | Any folder path in [Folder Paths][FolderPaths Property] points to a file. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains leading spaces. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | Any folder path in [Folder Paths][FolderPaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any folder path in [Folder Paths][FolderPaths Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to create a folder in the [Folder Paths][FolderPaths Property]. | +| | An unexpected error occurs when creating a folder in the [Folder Paths][FolderPaths Property] or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Paths][FolderPaths Property] does not contain any items. | | +| [PropertyNullException][] | Thrown when [Folder Paths][FolderPaths Property] is `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Paths need escaping + +Each folder path in [Folder Paths][FolderPaths Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the folder path (e.g. `@"C:\Source"`). + +### Folder Path already exists + +If a folder path in [Folder Paths][FolderPaths Property] already exists nothing is created, and no exception is thrown. + +### Handling of Exceptions + +If an exception occurs when trying to create a folder in [Folder Paths][FolderPaths Property], it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FolderPaths Property]: {{< ref "#folder-paths" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/_index.md new file mode 100644 index 000000000..e4e10375e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Delete File(s)" +linkTitle: "Delete File(s)" +description: "Delete a file or multiple files." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-file-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-file-block.md new file mode 100644 index 000000000..18d47a0d8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-file-block.md @@ -0,0 +1,110 @@ +--- +title: "Delete File" +linkTitle: "Delete File" +description: "Deletes a file at the specified file path." +--- + +{{< figure src="/blocks/files-delete-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.DeleteFile.DeleteFileBlock)
+ +## Description + +Deletes a file at the specified [File Path][FilePath Property]. + +## Examples + +### Delete a file + +This example will delete `"C:\Source\File.txt"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | + +#### Result + +Deleting `"C:\Source\File.txt"` results in the file `"File.txt"` being deleted from the folder `"C:\Source"`. + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to delete the file from. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +If the [File Path][FilePath Property] exists it is permanently deleted; it does not go into a recycle bin. + +If the [File Path][FilePath Property] does not exist no exception is thrown. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The file at the specified [File Path][FilePath Property] is read-only. | +| | The file at the specified [File Path][FilePath Property] is in use by another application. | +| | The user the flow is executing as does not have the required permissions to delete the file. | +| | An unexpected error occurs when deleting the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### File Path does not exist + +If the [File Path][FilePath Property] does not exist nothing is deleted, and no exception is thrown. + +[FilePath Property]: {{< ref "#file-path" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-files-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-files-block.md new file mode 100644 index 000000000..794ab5a9a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-file/delete-files-block.md @@ -0,0 +1,121 @@ +--- +title: "Delete Files" +linkTitle: "Delete Files" +description: "Deletes files at the specified file paths." +--- + +{{< figure src="/blocks/files-delete-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.DeleteFile.DeleteFilesBlock)
+ +## Description + +Deletes files at the specified [File Paths][FilePaths Property]. + +## Examples + +### Delete files + +This example will delete files `["C:\Source\File1.txt", "C:\Source\File2.txt"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\File1.txt", @"C:\Source\File2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Deleting `["C:\Source\File1.txt", "C:\Source\File2.txt"]` results in files `"File1.txt"` and `"File2.txt"` being deleted from the folder `"C:\Source"`. + +*** + +## Properties + +### File Paths + +The [File Paths][FilePaths Property] to delete the files from. + +Each file path in [File Paths][FilePaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +If a file path in [File Paths][FilePaths Property] exists it is permanently deleted; it does not go into a recycle bin. + +If a file path in [File Paths][FilePaths Property] does not exist no exception is recorded for that file path. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePaths` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | Any file path in [File Paths][FilePaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty File Paths][]. | +| | Any file path in [File Paths][FilePaths Property] is duplicated. For more information, see [Duplicate File Paths][]. | +| | Any file path in [File Paths][FilePaths Property] points to a folder. | +| | Any file path in [File Paths][FilePaths Property] contains leading spaces. | +| | Any file path in [File Paths][FilePaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | Any file path in [File Paths][FilePaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any file path in [File Paths][FilePaths Property] is invalid (for example, it is on an unmapped drive). | +| | Any file path in [File Paths][FilePaths Property] is read-only. | +| | Any file path in [File Paths][FilePaths Property] is in use by another application. | +| | The user the flow is executing as does not have the required permissions to delete a file in [File Paths][FilePaths Property]. | +| | An unexpected error occurs when deleting a file in [File Paths][FilePaths Property]. | +| [PropertyEmptyException][] | Thrown when [File Paths][FilePaths Property] does not contain any items. | +| [PropertyNullException][] | Thrown when [File Paths][FilePaths Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Paths need escaping + +Each file path in [File Paths][FilePaths Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the +file path (e.g. `@"C:\Source\File.txt"`). + +### File Path does not exist + +If a file path in [File Paths][FilePaths Property] does not exist no exception is recorded for that file path. + +### Handling of Exceptions + +If an exception occurs when trying to delete a file in the [File Paths][FilePaths Property], it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FilePaths Property]: {{< ref "#file-paths" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/_index.md new file mode 100644 index 000000000..03f110087 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Delete Folder(s)" +linkTitle: "Delete Folder(s)" +description: "Delete a folder or multiple folders." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folder-block.md new file mode 100644 index 000000000..b9746049c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folder-block.md @@ -0,0 +1,163 @@ +--- +title: "Delete Folder" +linkTitle: "Delete Folder" +description: "Deletes a folder at the specified folder path." +--- + +{{< figure src="/blocks/folders-delete-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.DeleteFolder.DeleteFolderBlock)
+ +## Description + +Deletes a folder at the specified [Folder Path][FolderPath Property]. + +A [Recursive][Recursive Property] option must be set to `true` to be able to delete a folder that contains files and/or other folders. This is to prevent unintentional and destructive deletion of files and folders. + +## Examples + +### Delete an empty folder + +This example will delete `"C:\Source\EmptyFolder"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\EmptyFolder"` | `($)FolderPath` is a variable of type [String][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `false` | `($)Recursive` is a variable of type [Boolean][] | + +#### Result + +Deleting `"C:\Source\EmptyFolder"` results in the folder `"EmptyFolder"` being deleted from the folder `"C:\Source"`. + +*** + +### Delete a folder and its content + +This example will delete `"C:\Source\Folder"` and its content. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * A file named `"FileInFolder.txt"`. + * An empty sub-folder named `"EmptySubFolder"`. + * An sub-folder named `"SubFolder"` that contains. + * A file named `"FileInSubFolder.txt"`. + +Therefore, recursive must be set to `true` to ensure child folders and files can be deleted. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `true` | `($)Recursive` is a variable of type [Boolean][] | + +#### Result + +Deleting `"C:\Source\Folder"` and its content results in: + +* File `"FileInSubFolder.txt"` being deleted from the folder `"C:\Source\Folder\SubFolder"`. +* Folder `"SubFolder"` being deleted from the folder `"C:\Source\Folder"`. +* Folder `"EmptySubFolder"` being deleted from the folder `"C:\Source\Folder"`. +* File `"FileInFolder.txt"` being deleted from the folder `"C:\Source\Folder"`. +* Folder `"Folder"` being deleted from the folder `"C:\Source"`. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to delete the folder from. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Recursive + +[Recursive][Recursive Property] option that must be set to `true` to be able to delete a folder that contains files and/or other folders. + +If [Recursive][Recursive Property] is set to `false`, only an empty folder will be able to be deleted; for a non-empty folder an [OperationFailedException][] will be thrown. + +By default, this is set to `false` to prevent unintentional and destructive deletion of files and folders. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The folder at the [Folder Path][FolderPath Property] is not empty and recursive is `false`. | +| | The folder at the [Folder Path][FolderPath Property] or any sub-folders are read-only or contain read-only files and/or folders. +| | The user the flow is executing as does not have the required permissions to delete the folder at the [Folder Path][FolderPath Property] or any of its content. | +| | An unexpected error occurs when deleting the folder at the [Folder Path][FolderPath Property] or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] is `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +### Folder Path does not exist + +If the [Folder Path][FolderPath Property] does not exist nothing is deleted, and no exception is thrown. + +### Handling of Exceptions + +If an exception occurs when trying to delete [Folder Path][FolderPath Property], an [OperationFailedException][] will be thrown. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[Recursive Property]: {{< ref "#recursive" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md new file mode 100644 index 000000000..1fdfb6cf1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md @@ -0,0 +1,178 @@ +--- +title: "Delete Folders" +linkTitle: "Delete Folders" +description: "Deletes folders at the specified folder paths." +--- + +{{< figure src="/blocks/folders-delete-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.DeleteFolder.DeleteFoldersBlock)
+ +## Description + +Deletes folders at the specified [Folder Paths][FolderPaths Property]. + +A [Recursive][Recursive Property] option must be set to `true` to be able to delete folders that contain files and/or other folders. This is to prevent unintentional and destructive deletion of files and folders. + +## Examples + +### Delete empty folders + +This example will delete `["C:\Source\EmptyFolder1", "C:\Source\EmptyFolder2"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\EmptyFolder1", @"C:\Source\EmptyFolder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Recursive][Recursive Property] | `($)Recursive`, with value `false` | `($)Recursive` is a variable of type [Boolean][] | + +#### Result + +Deleting `["C:\Source\EmptyFolder1", "C:\Source\EmptyFolder2"]` results in the folders `"EmptyFolder1"` and `"EmptyFolder2"` being deleted from the folder `"C:\Source"`. + +*** + +### Delete folders and their content + +This example will delete `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * A file named `"FileInFolder1.txt"`. + * An empty sub-folder named `"EmptySubFolder1"`. + * An sub-folder named `"SubFolder1"` that contains. + * A file named `"FileInSubFolder1.txt"`. +* `"C:\Source\Folder2"` contains: + * A file named `"FileInFolder2.txt"`. + * An empty sub-folder named `"EmptySubFolder2"`. + * An sub-folder named `"SubFolder2"` that contains. + * A file named `"FileInSubFolder2.txt"`. + +Therefore, recursive must be set to `true` to ensure child folders and files can be deleted. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Recursive][Recursive Property] | `($)Recursive`, with value `true` | `($)Recursive` is a variable of type [Boolean][] | + +#### Result + +Deleting `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` and their content results in: + +* File `"FileInSubFolder1.txt"` being deleted from the folder `"C:\Source\Folder1\SubFolder1"`. +* File `"FileInSubFolder2.txt"` being deleted from the folder `"C:\Source\Folder2\SubFolder2"`. +* Folder `"SubFolder1"` being deleted from the folder `"C:\Source\Folder1"`. +* Folder `"SubFolder2"` being deleted from the folder `"C:\Source\Folder2"`. +* Folder `"EmptySubFolder1"` being deleted from the folder `"C:\Source\Folder1"`. +* Folder `"EmptySubFolder2"` being deleted from the folder `"C:\Source\Folder2"`. +* File `"FileInFolder1.txt"` being deleted from the folder `"C:\Source\Folder1"`. +* File `"FileInFolder2.txt"` being deleted from the folder `"C:\Source\Folder2"`. +* Folder `"Folder1"` being deleted from the folder `"C:\Source"`. +* Folder `"Folder2"` being deleted from the folder `"C:\Source"`. + +*** + +## Properties + +### Folder Paths + +The [Folder Paths][FolderPaths Property] to delete the folders from. + +Each folder path in [Folder Paths][FolderPaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPaths` with no value | + +### Recursive + +[Recursive][Recursive Property] option that must be set to `true` to be able to delete folders that contain files and/or other folders. + +If [Recursive][Recursive Property] is set to `false`, only empty folders will be able to be deleted; for non-empty folders an [OperationFailedException][] will be thrown. + +By default, this is set to `false` to prevent unintentional and destructive deletion of files and folders. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | Any folder path in [Folder Paths][FolderPaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty Folder Paths][]. | +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. For more information, see [Duplicate Folder Paths][]. | +| | Any folder path in [Folder Paths][FolderPaths Property] points to a file. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains leading spaces. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | Any folder path in [Folder Paths][FolderPaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any folder path in [Folder Paths][FolderPaths Property] is not empty and recursive is `false`. | +| | Any folder path in [Folder Paths][FolderPaths Property] or any of their sub-folders are read-only or contain read-only files and/or folders. +| | The user the flow is executing as does not have the required permissions to delete a folder in the [Folder Paths][FolderPaths Property] or any of its content. | +| | An unexpected error occurs when deleting a folder in the [Folder Paths][FolderPaths Property] or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Paths][FolderPaths Property] does not contain any items. | | +| [PropertyNullException][] | Thrown when [Folder Paths][FolderPaths Property] is `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Paths need escaping + +Each folder path in [Folder Paths][FolderPaths Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the folder path (e.g. `@"C:\Source"`). + +### Folder Path does not exist + +If a folder path in [Folder Paths][FolderPaths Property] does not exist no exception is recorded for that folder path. + +### Handling of Exceptions + +If an exception occurs when trying to delete a folder in [Folder Paths][FolderPaths Property], it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FolderPaths Property]: {{< ref "#folder-paths" >}} +[Recursive Property]: {{< ref "#recursive" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/_index.md new file mode 100644 index 000000000..e2945e03a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get File Information" +linkTitle: "Get File Information" +description: "Get information about a file (i.e. file attributes, created, accessed and modified dates etc.)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/get-file-information-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/get-file-information-block.md new file mode 100644 index 000000000..c81732e36 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-file-information/get-file-information-block.md @@ -0,0 +1,154 @@ +--- +title: "Get File Information" +linkTitle: "Get File Information" +description: "Gets information about a file (e.g. file attributes, created, accessed, modified dates etc.) at the specified file path." +--- + +{{< figure src="/blocks/files-get-information-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.GetFileInformation.GetFileInformationBlock)
+ +## Description + +Gets [File Information][FileInformation Property] about a file (e.g. file attributes, created, accessed, modified dates etc.) at the specified [File Path][FilePath Property]. + +## Examples + +### Get file information + +This example will get information about `"C:\Source\File.txt"`. + +In this example assume `"C:\Source\File.txt"`: + +* Is on a server where local time and UTC time are the same (e.g. in UK). +* Was created at 10.00am on the 1st January 2021. +* Was last modified at 10.00am on the 1st January 2021. +* Was last accessed at 1.00pm on the 10th January 2021. +* Is 100 bytes in size. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [File Information][FileInformation Property] | `($)FileInformation`, with no value | `($)FilePath` is a variable that will be set to a [FileInformation][] value | + +#### Result + +Getting file information for `"C:\Source\File.txt"` results in the variable `($)FileInformation` being updated to the following: + +```json +{ + "Extension": ".exe", + "Path": "C:\\Source\\File.txt", + "Name": "File.txt", + "ParentRoot": "C:\\", + "ParentPath": "C:\\Source", + "SizeInBytes": 100, + "IsArchive": false, + "IsCompressed": false, + "IsEncrypted": false, + "IsHidden": false, + "IsNormal": false, + "IsTemporary": false, + "IsReadOnly": false, + "IsSystem": false, + "CreationTimeLocal": "2021-01-01T10:00:00+00:00", + "CreationTimeUtc": "2021-01-01T10:00:00Z", + "LastAccessTimeLocal": "2021-01-10T13:00:00+00:00", + "LastAccessTimeUtc": "2021-01-10T13:00:00Z", + "LastWriteTimeLocal": "2021-01-01T10:00:00+00:00", + "LastWriteTimeUtc": "2021-01-01T10:00:00Z" +} +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to get the [File Information][FileInformation Property] of. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### File Information + +The [File Information][FileInformation Property] retrieved from the file at the specified [File Path][FilePath Property]. + +[File Information][FileInformation Property] includes file attributes, create, access and write dates and path details. + +For more information see the [example][] above, or the [FileInformation][] data type. + +| | | +|--------------------|---------------------------| +| Data Type | [FileInformation][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FileInformation` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder or file names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to get information about the file at the [File Path][FilePath Property]. | +| | An unexpected error occurs when getting information for the file at the [File Path][FilePath Property]. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +[FilePath Property]: {{< ref "#file-path" >}} +[FileInformation Property]: {{< ref "#file-information" >}} +[Example]: {{< ref "#get-file-information" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[FileInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FileInformation.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/_index.md new file mode 100644 index 000000000..4c4696535 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Folder Content" +linkTitle: "Get Folder Content" +description: "Get the paths of files or folders in another folder." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/get-folder-content-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/get-folder-content-block.md new file mode 100644 index 000000000..7c5830db9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-content/get-folder-content-block.md @@ -0,0 +1,389 @@ +--- +title: "Get Folder Content" +linkTitle: "Get Folder Content" +description: "Gets the paths of files or folders under the specified folder path." +--- + +{{< figure src="/blocks/folders-get-content-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.GetFolderContent.GetFolderContentBlock)
+ +## Description + +Gets the [Paths][Paths Property] of files or folders under the specified [Folder Path][FolderPath Property] whose name matches the given [Search Pattern][SearchPattern Property]. + +The returned [Paths][Paths Property] can then be used in other file and folder blocks that require paths. + +Additional options can be specified: + +* [Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search. +* [Content Options][ContentOptions Property] can be specified to choose whether to search for files or folders. +* A [Recursive][Recursive Property] option can specified to choose whether to search only in the specified [Folder Path][FolderPath Property], or include all subfolders. +* A [Comparison Type][ComparisonType Property] option can specified to choose how it is determined whether the file or folder name matches the [Search Pattern][SearchPattern Property] (e.g. whether the search is case-sensitive or case-insensitive). + +## Examples + +### Get paths of files in a folder whose names contain a given text + +This example will get the paths of all files in `"C:\Source\Folder"` that contain `"file"` in their name. + +It will perform a case-insensitive search, and will not get any paths of folders or any paths of files that reside in subfolders of `"C:\Source\Folder"`. + +In this example assume `"C:\Source\Folder"` contains: + +* A file named `"FileInFolder1.txt"`. +* A file named `"FileInFolder2.txt"`. +* A folder named `"SubFolder"` which contains: + * A file named `"FileInSubFolder1.txt"`. + * A file named `"FileInSubFolder2.txt"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"file"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Content Options][ContentOptions Property] | `($)ContentOptions`, with value `ContentOptions.Files` | `($)ContentOptions` is a variable of type [ContentOptions][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `false` | `($)Recursive` is a variable of type [Boolean][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Paths][Paths Property] | `($)Paths`, with no value | `($)Paths` is a variable that will be set to an [IList][]<[String][]> value | + +#### Result + +Getting all file paths that contain `"file"` (case-insensitive) in `"C:\Source\Folder"` excluding any of its subfolders, results in the variable `($)Paths` being updated to the following: + +```json +[ + "C:\\Source\\Folder\\FileInFolder1.txt", + "C:\\Source\\Folder\\FileInFolder2.txt" +] +``` + +*** + +### Get paths of files in a folder (and its subfolders) whose names contain a given text + +This example will get the paths of all files in `"C:\Source\Folder"` or any of its subfolders, that contain `"File"` in their name. + +It will perform a case-sensitive search and will not get any paths of folders. + +In this example assume `"C:\Source\Folder"` contains: + +* A file named `"FileInFolder1.txt"`. +* A file named `"FileInFolder2.txt"`. +* A folder named `"SubFolder"` which contains: + * A file named `"FileInSubFolder1.txt"`. + * A file named `"FileInSubFolder2.txt"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"File"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Content Options][ContentOptions Property] | `($)ContentOptions`, with value `ContentOptions.Files` | `($)ContentOptions` is a variable of type [ContentOptions][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `true` | `($)Recursive` is a variable of type [Boolean][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Paths][Paths Property] | `($)Paths`, with no value | `($)Paths` is a variable that will be set to an [IList][]<[String][]> value | + +#### Result + +Getting all file paths that contain `"File"` (case-sensitive) in `"C:\Source\Folder"` or any of its subfolders, results in the variable `($)Paths` being updated to the following: + +```json +[ + "C:\\Source\\Folder\\FileInFolder1.txt", + "C:\\Source\\Folder\\FileInFolder2.txt", + "C:\\Source\\Folder\\SubFolder\\FileInSubFolder1.txt", + "C:\\Source\\Folder\\SubFolder\\FileInSubFolder2.txt" +] +``` + +*** + +### Get paths of folders in a folder whose names match a given pattern + +This example will get the paths of all folders that are in `"C:\Source\Folder"`, and match the pattern `"*"` in their name. + +It will perform a case-insensitive search, will not get any paths of files, and will match any folder in `"C:\Source\Folder"`. It will not match any child folders of folders in `"C:\Source\Folder"`. + +In this example assume `"C:\Source\Folder"` contains: + +* A file named `"FileInFolder1.txt"`. +* A file named `"FileInFolder2.txt"`. +* A folder named `"SubFolder"` which contains: + * A file named `"FileInSubFolder1.txt"`. + * A file named `"FileInSubFolder2.txt"`. + * An empty folder named `"NestedSubFolder"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"*"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Content Options][ContentOptions Property] | `($)ContentOptions`, with value `ContentOptions.Folders` | `($)ContentOptions` is a variable of type [ContentOptions][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `false` | `($)Recursive` is a variable of type [Boolean][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Paths][Paths Property] | `($)Paths`, with no value | `($)Paths` is a variable that will be set to an [IList][]<[String][]> value | + +#### Result + +Getting all folder paths that match the pattern `"*"` (case-insensitive) in `"C:\Source\Folder"` excluding any of its subfolders, results in the variable `($)Paths` being updated to the following: + +```json +[ + "C:\\Source\\Folder\\SubFolder" +] +``` + +*** + +### Get paths of folders in a folder (and its subfolders) whose names match a given regex + +This example will get the paths of all folders that are in `"C:\Source\Folder"` or any of its subfolders, and match the regex `"Folder$"` in their name. + +It will perform a case-sensitive search, will not get any paths of files, and will match folders whose name ends with `"Folder"`. + +In this example assume `"C:\Source\Folder"` contains: + +* A file named `"FileInFolder1.txt"`. +* A file named `"FileInFolder2.txt"`. +* A folder named `"SubFolder"` which contains: + * A file named `"FileInSubFolder1.txt"`. + * A file named `"FileInSubFolder2.txt"`. + * An empty folder named `"NestedSubFolder"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"Folder$"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Content Options][ContentOptions Property] | `($)ContentOptions`, with value `ContentOptions.Folders` | `($)ContentOptions` is a variable of type [ContentOptions][] | +| [Recursive][Recursive Property] | `($)Recursive`, with value `true` | `($)Recursive` is a variable of type [Boolean][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Paths][Paths Property] | `($)Paths`, with no value | `($)Paths` is a variable that will be set to an [IList][]<[String][]> value | + +#### Result + +Getting all folder paths that match the regex `"Folder$"` (case-sensitive) in `"C:\Source\Folder"` or any of its subfolders, results in the variable `($)Paths` being updated to the following: + +```json +[ + "C:\\Source\\Folder\\SubFolder", + "C:\\Source\\Folder\\SubFolder\\NestedSubFolder" +] +``` + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to get the [Paths][Paths Property] of files or folders whose name matches the given [Search Pattern][SearchPattern Property]. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Search Pattern + +The [Search Pattern][SearchPattern Property] file or folder names must match to be included in the returned [Paths][Paths Property]. + +Only file or folder names are matched, not the whole path. + +A [Search Pattern][SearchPattern Property] of `null` or empty (i.e. `""`) means match any name; all additional block options such as [Content Options][ContentOptions Property] etc. still take effect. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Search Pattern][SearchPattern Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the file or folder name contains the text specified in [Search Pattern][SearchPattern Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Content Options + +[Content Options][ContentOptions Property] can be specified to choose whether [Search Pattern][SearchPattern Property] should be match file or folder names. + +* ContentOptions.Files restricts the search to match only files. +* ContentOptions.Folders restricts the search to match only folders. + +| | | +|--------------------|---------------------------| +| Data Type | [ContentOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `Files` | + +### Recursive + +[Recursive][Recursive Property] option can specified to choose whether to search only in the specified [Folder Path][FolderPath Property], or include all subfolders. + +To search only in the specified [Folder Path][FolderPath Property] set [Recursive][Recursive Property] to `false`, or to include all subfolders set [Recursive][Recursive Property] to `true`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match file or folder names against the given [Search Pattern][SearchPattern Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Paths + +All [Paths][Paths Property] that match the specified [Search Pattern][SearchPattern Property] based on the other specified options. + +The [Paths][Paths Property] returned will be absolute paths, and based on the [Folder Path][FolderPath Property] provided (i.e. if a UNC path is specified, all returned paths will be UNC paths). + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Paths` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| | Thrown when [Content Options][ContentOptions Property] is not one of the specified [ContentOptions][] types (e.g. `(ContentOptions)10`). | +| | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| [OperationFailedException][] | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to get the paths of files or folders in the [Folder Path][FolderPath Property], or any of its subfolders if [Recursive][Recursive Property] is `true`. | +| | An unexpected error occurs when getting the paths of files or folders in the [Folder Path][FolderPath Property], or any of its subfolders if [Recursive][Recursive Property] is `true`. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] is `null`. | +| [RegexMatchTimeoutException][] | Thrown when using [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and the [Search Pattern][SearchPattern Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +### Null or empty Search Pattern + +A `null` or empty (i.e. `""`) [Search Pattern][SearchPattern Property] means match any name; all additional block options such as [Content Options][ContentOptions Property] etc. still take effect. + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Handling of Exceptions + +If an exception occurs when trying to match a file or folder name, it will be recorded and the block will continue processing the remaining files or folders. Once all files or folders are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[SearchPattern Property]: {{< ref "#search-pattern" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ContentOptions Property]: {{< ref "#content-options" >}} +[Recursive Property]: {{< ref "#recursive" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Paths Property]: {{< ref "#paths" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} +[ContentOptions]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.ContentOptions.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/_index.md new file mode 100644 index 000000000..9b3213535 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Folder Information" +linkTitle: "Get Folder Information" +description: "Get information about a folder (i.e. folder attributes, created, accessed and modified dates etc.)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/get-folder-information-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/get-folder-information-block.md new file mode 100644 index 000000000..ab7c0b1e2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/get-folder-information/get-folder-information-block.md @@ -0,0 +1,158 @@ +--- +title: "Get Folder Information" +linkTitle: "Get Folder Information" +description: "Gets information about a folder (e.g. folder attributes, created, accessed, modified dates etc.) at the specified folder path." +--- + +{{< figure src="/blocks/folders-get-information-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.GetFolderInformation.GetFolderInformationBlock)
+ +## Description + +Gets [Folder Information][FolderInformation Property] about a folder (e.g. folder attributes, created, accessed, modified dates etc.) at the specified [Folder Path][FolderPath Property]. + +## Examples + +### Get folder information + +This example will get information about `"C:\Source\Folder"`. + +In this example assume `"C:\Source\Folder"`: + +* Is on a server where local time and UTC time are the same (e.g. in UK). +* Was created at 10.00am on the 1st January 2021. +* Was last modified at 10.00am on the 1st January 2021. +* Was last accessed at 1.00pm on the 10th January 2021. +* Contains a single file named `"File.txt"` which is 100 bytes in size. +* Contains a single empty folder named `"SubFolder"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Folder Information][FolderInformation Property] | `($)FolderInformation`, with no value | `($)FolderPath` is a variable that will be set to a [FolderInformation][] value | + +#### Result + +Getting folder information for `"C:\Source\Folder"` results in the variable `($)FolderInformation` being updated to the following: + +```json +{ + "FileCount": 1, + "FolderCount": 1, + "TotalItemCount": 2, + "Path": "C:\\Source\\Folder", + "Name": "Test", + "ParentRoot": "C:\\", + "ParentPath": "C:\\Source", + "SizeInBytes": 100, + "IsArchive": false, + "IsCompressed": false, + "IsEncrypted": false, + "IsHidden": false, + "IsNormal": false, + "IsTemporary": false, + "IsReadOnly": false, + "IsSystem": false, + "CreationTimeLocal": "2021-01-01T10:00:00+00:00", + "CreationTimeUtc": "2021-01-01T10:00:00Z", + "LastAccessTimeLocal": "2021-01-10T13:00:00+00:00", + "LastAccessTimeUtc": "2021-01-10T13:00:00Z", + "LastWriteTimeLocal": "2021-01-01T10:00:00+00:00", + "LastWriteTimeUtc": "2021-01-01T10:00:00Z" +} +``` + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to get the [Folder Information][FolderInformation Property] of. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Folder Information + +The [Folder Information][FolderInformation Property] retrieved from the folder at the specified [Folder Path][FolderPath Property]. + +[Folder Information][FolderInformation Property] includes folder attributes, create, access and write dates, path details and folder and file counts. + +For more information see the [example][] above, or the [FolderInformation][] data type. + +| | | +|--------------------|---------------------------| +| Data Type | [FolderInformation][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderInformation` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [OperationFailedException][] | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to get information about the folder at the [Folder Path][FolderPath Property]. | +| | An unexpected error occurs when getting information for the folder at the [Folder Path][FolderPath Property] or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] is `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +[FolderPath Property]: {{< ref "#folder-path" >}} +[FolderInformation Property]: {{< ref "#folder-information" >}} + +[Example]: {{< ref "#get-folder-information" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[FolderInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FolderInformation.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/_index.md new file mode 100644 index 000000000..72624ef3e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Move File(s)" +linkTitle: "Move File(s)" +description: "Move a file or multiple files." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-file-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-file-block.md new file mode 100644 index 000000000..fde37d7c6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-file-block.md @@ -0,0 +1,223 @@ +--- +title: "Move File" +linkTitle: "Move File" +description: "Moves a file at the specified file path to the given destination path." +--- + +{{< figure src="/blocks/files-move-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.MoveFile.MoveFileBlock)
+ +## Description + +Moves a file at the specified [File Path][FilePath Property] to the given [Destination Path][DestinationPath Property], with an option to [Overwrite][Overwrite Property] the file if it already exists. + +## Examples + +### Move a file to a folder keeping the same file name + +This example will move `"C:\Source\OriginalFile.txt"` to `"C:\Destination"`, with the same file name of `"OriginalFile.txt"`. + +In this example assume `"C:\Destination"` does not already contain a file named `"OriginalFile.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\OriginalFile.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\OriginalFile.txt"` to `"C:\Destination"` that does not already contain a file named `"OriginalFile.txt"` will: + +* Move `"C:\Source\OriginalFile.txt"` to `"C:\Destination\OriginalFile.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move a file to a folder with a new name + +This example will move `"C:\Source\OriginalFile.txt"` to `"C:\Destination"`, with a new file name of `"NewFile.txt"`. + +To rename the file when it is being moved, please note that the [Destination Path][DestinationPath Property] must be a file path, rather than a folder path (e.g. `"C:\Destination\NewFile.txt"` rather than `"C:\Destination"`). + +In this example assume `"C:\Destination"` does not already contain a file named `"NewFile.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\OriginalFile.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination\NewFile.txt"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Move `"C:\Source\OriginalFile.txt"` to the path `"C:\Destination\NewFile.txt"` that does not already exist will: + +* Move `"C:\Source\OriginalFile.txt"` to `"C:\Destination\NewFile.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move a file to a folder overwriting any file that already exists with the same name + +This example will move `"C:\Source\FileAlreadyExists.txt"` to `"C:\Destination"`, with the same file name of `"FileAlreadyExists.txt"`. + +In this example assume `"C:\Destination"` already contains a file named `"FileAlreadyExists.txt"`, so overwrite must be set to `true` to ensure the content of the existing file can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\FileAlreadyExists.txt"` | `($)FilePath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\FileAlreadyExists.txt"` to `"C:\Destination"` and overwriting the existing file named `"FileAlreadyExists.txt"` will: + +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists.txt"`. + * The `Date Created` copied from `"C:\Source\FileAlreadyExists.txt"`. + * The `Date Accessed` copied from `"C:\Source\FileAlreadyExists.txt"` + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists.txt"`. + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to move the file from. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to move the file to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] can either point to a folder or a file: + +* If it points to a folder, the moved file will have the name specified in the [File Path][FilePath Property]. +* If it points to a file, the moved file will have the name specified in the [Destination Path][DestinationPath Property]. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the file in the [Destination Path][DestinationPath Property] if it already exists. + +If the file exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [Destination Path][DestinationPath Property] (if it points to a file), or the [Destination Path][DestinationPath Property] (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [File Path][FilePath Property] does not exist. | +| | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | The file in the specified [Destination Path][DestinationPath Property] exists and overwrite is `false`. | +| | The file in the specified [Destination Path][DestinationPath Property] exists, is read-only and overwrite is `true`. | +| | The user the flow is executing as does not have the required permissions to move the file (e.g. not having read access to the [File Path][FilePath Property] or write access to the [Destination Path][DestinationPath Property]). | +| | An unexpected error occurs when moving the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### File and Folder Paths + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path and Destination Path need escaping + +[File Path][FilePath Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\OriginalFile.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\OriginalFile.txt"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### File Attributes + +When moving a file from the [File Path][FilePath Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes will also be moved. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +[FilePath Property]: {{< ref "#file-path" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} + +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md new file mode 100644 index 000000000..c223d3da7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md @@ -0,0 +1,216 @@ +--- +title: "Move Files" +linkTitle: "Move Files" +description: "Moves files at the specified file paths to the given destination path." +--- + +{{< figure src="/blocks/files-move-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.MoveFile.MoveFilesBlock)
+ +## Description + +Moves files at the specified [File Paths][FilePaths Property] to the given [Destination Path][DestinationPath Property], with an option to [Overwrite][Overwrite Property] the files if they already exist. + +## Examples + +### Move files to a folder keeping the same file names + +This example will move `["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"]` to `"C:\Destination"`, with the same file names of `"OriginalFile1.txt"` and `"OriginalFile2.txt"`. + +In this example assume `"C:\Destination"` does not already contain a file named `"OriginalFile1.txt"` or a file named `"OriginalFile2.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\OriginalFile1.txt", @"C:\Source\OriginalFile2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"]` to `"C:\Destination"` that does not already contain files named `"OriginalFile1.txt"` and `"OriginalFile2.txt"` will: + +* Move `"C:\Source\OriginalFile1.txt"` to `"C:\Destination\OriginalFile1.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Move `"C:\Source\OriginalFile2.txt"` to `"C:\Destination\OriginalFile2.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move files to a folder overwriting any files that already exists with the same names + +This example will move `["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"]` to `"C:\Destination"`, with the same file names of `"FileAlreadyExists1.txt"` and `"FileAlreadyExists2.txt"`. + +In this example assume `"C:\Destination"` already contains a file named `"FileAlreadyExists1.txt"` and a file named `"FileAlreadyExists2.txt"`, so overwrite must be set to `true` to ensure the content of the existing files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\FileAlreadyExists1.txt", @"C:\Source\FileAlreadyExists2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"]` to `"C:\Destination"` and overwriting the existing files named `"FileAlreadyExists1.txt"` and `"FileAlreadyExists2.txt"` will: + +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists1.txt"`. + * The `Date Created` copied from `"C:\Source\FileAlreadyExists1.txt"`. + * The `Date Accessed` copied from `"C:\Source\FileAlreadyExists1.txt"` + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists1.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists1.txt"`. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The `Date Created` copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The `Date Accessed` copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The `Date Modified` copied from `"C:\Source\FileAlreadyExists2.txt"`. + * The [File Attributes][] copied from `"C:\Source\FileAlreadyExists2.txt"`. + +*** + +## Properties + +### File Paths + +The [File Paths][FilePaths Property] to move the files from. + +Each file path in [File Paths][FilePaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePaths` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to move the files to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The moved files will have the names specified in the [File Paths][FilePaths Property]. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the files in the [Destination Path][DestinationPath Property] if they already exist. + +If any file exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] does not point to a folder. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [Destination Path][DestinationPath Property] (if it points to a file), or the [Destination Path][DestinationPath Property] (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | Any file path in [File Paths][FilePaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty File Paths][]| +| | Any file path in [File Paths][FilePaths Property] is duplicated. For more information, see [Duplicate File Paths][] | +| | Any file path in [File Paths][FilePaths Property] does not exist. | +| | Any file path in [File Paths][FilePaths Property] points to a folder. | +| | Any file path in [File Paths][FilePaths Property] contains leading spaces. | +| | Any file path in [File Paths][FilePaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | Any file path in [File Paths][FilePaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any file path in [File Paths][FilePaths Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | Any file path in [File Paths][FilePaths Property] exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file path in [File Paths][FilePaths Property] exists in the specified [Destination Path][DestinationPath Property] with the same name, is read-only and overwrite is `true`. | +| | The user the flow is executing as does not have the required permissions to move any file (e.g. not having read access to a file path in [File Paths][FilePaths Property] or write access to the [Destination Path][DestinationPath Property]). | +| | An unexpected error occurs when moving a file. | +| [PropertyEmptyException][] | Thrown when [File Paths][FilePaths Property] does not contain any items, or [Destination Path][DestinationPath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Paths][FilePaths Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### File and Folder Paths + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Paths and Destination Path need escaping + +Each file path in [File Paths][FilePaths Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\OriginalFile.txt"`), or +* Prepending an `@` character before the start of the +file path (e.g. `@"C:\Source\OriginalFile.txt"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### File Attributes + +When moving a file in the [File Paths][FilePaths Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes will also be moved. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Handling of Exceptions + +If an exception occurs when trying to move a file in the [File Paths][FilePaths Property], it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FilePaths Property]: {{< ref "#file-paths" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} + +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/_index.md new file mode 100644 index 000000000..facdb6dda --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Move Folder(s)" +linkTitle: "Move Folder(s)" +description: "Move a folder or folders." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folder-block.md new file mode 100644 index 000000000..8ee7aa3e4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folder-block.md @@ -0,0 +1,384 @@ +--- +title: "Move Folder" +linkTitle: "Move Folder" +description: "Moves a folder at the specified folder path to the given destination path." +--- + +{{< figure src="/blocks/folders-move-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.MoveFolder.MoveFolderBlock)
+ +## Description + +Moves a folder at the specified [Folder Path][FolderPath Property] to the given [Destination Path][DestinationPath Property], with an option to move the folder and its content, or just its [Content Only][ContentOnly Property]. + +An option can also be specified to [Overwrite][Overwrite Property] anything being moved that already exists in the [Destination Path][DestinationPath Property]. + +## Examples + +### Move a folder and its content + +This example will move `"C:\Source\Folder"` and its content to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. +* `"C:\Destination"` does not already contain a folder named `"Folder"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\Folder"` and its content to `"C:\Destination"` that does not already contain a folder named `"Folder"` will: + +* Move `"C:\Source\Folder"` to `"C:\Destination\Folder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\SubFolder"` to `"C:\Destination\Folder\SubFolder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\File.txt"` to `"C:\Destination\Folder\File.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move a folder and its content, overwriting any content that already exists + +This example will move `"C:\Source\Folder"` and its content to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * An empty sub-folder named `"SubFolderAlreadyExists"`. + * A file named `"File.txt"`. + * A file named `"FileAlreadyExists.txt"`. +* `"C:\Destination"` already contains a folder named `"Folder"`, which already contains: + * A folder named `"SubFolderAlreadyExists"`. + * A file named `"FileAlreadyExists.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing `"SubFolderAlreadyExists"` and `"FileAlreadyExists.txt"` can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\Folder"` and its content to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\Folder"`, `"C:\Destination\Folder\SubFolderAlreadyExists"` and `"C:\Destination\Folder\FileAlreadyExists.txt"` already exist will: + +* Overwrite the existing folder at `"C:\Destination\Folder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the move occurred. + * The `Date Modified` set to the time the move occurred. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\SubFolder"` to `"C:\Destination\Folder\SubFolder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\Folder\SubFolderAlreadyExists"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\File.txt"` to `"C:\Destination\Folder\File.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\Folder\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Created` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + +*** + +### Move a folder's content only + +This example will move `"C:\Source\Folder"` content only to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. +* `"C:\Destination"` does not already contain a folder named `"SubFolder"` or a file named `"File.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\Folder"` content only to `"C:\Destination"` that does not already contain a folder named `"SubFolder"` or a file named `"File.txt"` will: + +* Move `"C:\Source\Folder\SubFolder"` to `"C:\Destination\SubFolder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\File.txt"` to `"C:\Destination\File.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move a folder's content only, overwriting any content that already exists + +This example will move `"C:\Source\Folder"` content only to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * An empty sub-folder named `"SubFolderAlreadyExists"`. + * A file named `"File.txt"`. + * A file named `"FileAlreadyExists.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"SubFolderAlreadyExists"`. + * A file named `"FileAlreadyExists.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing `"SubFolderAlreadyExists"` and `"FileAlreadyExists.txt"` can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `"C:\Source\Folder"` content only to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\SubFolderAlreadyExists"` and `"C:\Destination\FileAlreadyExists.txt"` already exist will: + +* Move `"C:\Source\Folder\SubFolder"` to `"C:\Destination\SubFolder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder\File.txt"` to `"C:\Destination\File.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists.txt"` with: + * The content copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Created` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder\FileAlreadyExists.txt"`. + +*** + +### Move a folder and its content to the same location but with a different name + +If it is required to move a folder and its content into the same folder it is currently located in, but with a different name, then it is not possible to do with this block; the [Rename Folder][] block must be used instead. + +*** + +### Move a folder and its content to a different location but with a different name + +If it is required to move a folder and its content into a different folder than the one it is currently located in, but with a different name, it is not possible to do with a single block; you must use a combination of this block and the [Rename Folder][] block. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] to move the folder and/or its content from. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to move the folder and/or its content to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The moved folders and files will have the same names as the folders and files moved. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the folder and/or contents being moved to in the [Destination Path][DestinationPath Property] if they already exist. + +If the folder and/or contents exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing folders and files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Content Only + +Option to specify whether to move the folder and its content or just the [Content Only][ContentOnly Property]. + +To move the folder and its content, [Content Only][ContentOnly Property] must be set to `false`; to move just the content, [Content Only][ContentOnly Property] must be set to `true`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] points to a file. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Destination Path][DestinationPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [Folder Path][FolderPath Property] does not exist. | +| | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | The [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | The [Folder Path][FolderPath Property] and [Destination Path][DestinationPath Property] point to the same folder and [Content Only][ContentOnly Property] is `true`. | +| | The [Folder Path][FolderPath Property] is a child folder in the [Destination Path][DestinationPath Property] and [Content Only][ContentOnly Property] is `false`. | +| | Any file being moved already exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file being moved already exists in the specified [Destination Path][DestinationPath Property], is read-only and overwrite is `true`. | +| | The user the flow is executing as does not have the required permissions to move the folder or any of its content (e.g. not having read access to the [Folder Path][FolderPath Property] or its content, or write access to the [Destination Path][DestinationPath Property]). | +| | The operation is cyclic (e.g. moving a folder into one of its sub-folders). | +| | An unexpected error occurs when moving the folder or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path and Destination Path need escaping + +[Folder Path][FolderPath Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### Folder Attributes + +When moving the folder at the specified [Folder Path][FolderPath Property] or any folder under it to the new [Destination Path][DestinationPath Property], if the folder already exists in the destination its attributes remain unchanged. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### File Attributes + +When moving a file under [Folder Path][FolderPath Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes are also moved. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Handling of Exceptions + +If an exception occurs when trying to move [Folder Path][FolderPath Property], an [OperationFailedException][] will be thrown. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[ContentOnly Property]: {{< ref "#content-only" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md new file mode 100644 index 000000000..8ebdd0aee --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md @@ -0,0 +1,496 @@ +--- +title: "Move Folders" +linkTitle: "Move Folders" +description: "Moves folders at the specified folder paths to the given destination path." +--- + +{{< figure src="/blocks/folders-move-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.MoveFolder.MoveFoldersBlock)
+ +## Description + +Moves folders at the specified [Folder Paths][FolderPaths Property] to the given [Destination Path][DestinationPath Property], with an option to move the folders and their content, or just their [Content Only][ContentOnly Property]. + +An option can also be specified to [Overwrite][Overwrite Property] anything being moved that already exists in the [Destination Path][DestinationPath Property]. + +## Examples + +### Move folders and their content + +This example will move `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * A file named `"File1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * A file named `"File2.txt"`. +* `"C:\Destination"` does not already contain a folder named `"Folder1"` or `"Folder2"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"` that does not already contain folders named `"Folder1"` and `"Folder2"` will: + +* Move `"C:\Source\Folder1"` to `"C:\Destination\Folder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\SubFolder1"` to `"C:\Destination\Folder1\SubFolder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\File1.txt"` to `"C:\Destination\Folder1\File1.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Move `"C:\Source\Folder2"` to `"C:\Destination\Folder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\SubFolder2"` to `"C:\Destination\Folder2\SubFolder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\File2.txt"` to `"C:\Destination\Folder2\File2.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move folders and their content, overwriting any content that already exists + +This example will move `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * An empty sub-folder named `"SubFolderAlreadyExists1"`. + * A file named `"File1.txt"`. + * A file named `"FileAlreadyExists1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * An empty sub-folder named `"SubFolderAlreadyExists2"`. + * A file named `"File2.txt"`. + * A file named `"FileAlreadyExists2.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"Folder1"`, which already contains: + * A folder named `"SubFolderAlreadyExists1"`. + * A file named `"FileAlreadyExists1.txt"`. + * A folder named `"Folder2"`, which already contains: + * A folder named `"SubFolderAlreadyExists2"`. + * A file named `"FileAlreadyExists2.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing folders and files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `false` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\Folder1", "C:\Source\Folder2"]` and their content to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\Folder1"`, `"C:\Destination\Folder1\SubFolderAlreadyExists1"`, `"C:\Destination\Folder1\FileAlreadyExists1.txt"`, `"C:\Destination\Folder2"`, `"C:\Destination\Folder2\SubFolderAlreadyExists2"` and `"C:\Destination\Folder2\FileAlreadyExists2.txt"` already exist will: + +* Overwrite the existing folder at `"C:\Destination\Folder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the move occurred. + * The `Date Modified` set to the time the move occurred. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\SubFolder1"` to `"C:\Destination\Folder1\SubFolder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\Folder1\SubFolderAlreadyExists1"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\File1.txt"` to `"C:\Destination\Folder1\File1.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\Folder1\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Created` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. +* Overwrite the existing folder at `"C:\Destination\Folder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` set to the time the move occurred. + * The `Date Modified` set to the time the move occurred. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\SubFolder2"` to `"C:\Destination\Folder2\SubFolder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\Folder2\SubFolderAlreadyExists2"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\File2.txt"` to `"C:\Destination\Folder2\File2.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\Folder2\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Created` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + +*** + +### Move the folders' content only + +This example will move `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"`. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * A file named `"File1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * A file named `"File2.txt"`. +* `"C:\Destination"` does not already contain a folder named `"SubFolder1"` or `"SubFolder2"` or a file named `"File1.txt"` or `"File2.txt"`, so overwrite can be set to either `true` or `false` and it will still work. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"` that does not already contain a folder named `"SubFolder1"` or `"SubFolder2"` or a file named `"File1.txt"` or `"File2.txt"` will: + +* Move `"C:\Source\Folder1\SubFolder1"` to `"C:\Destination\SubFolder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\File1.txt"` to `"C:\Destination\File1.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Move `"C:\Source\Folder2\SubFolder2"` to `"C:\Destination\SubFolder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\File2.txt"` to `"C:\Destination\File2.txt"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. + +*** + +### Move folders' content only, overwriting any content that already exists + +This example will move `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"`, overwriting any content that already exists. + +In this example assume: + +* `"C:\Source\Folder1"` contains: + * An empty sub-folder named `"SubFolder1"`. + * An empty sub-folder named `"SubFolderAlreadyExists1"`. + * A file named `"File1.txt"`. + * A file named `"FileAlreadyExists1.txt"`. +* `"C:\Source\Folder2"` contains: + * An empty sub-folder named `"SubFolder2"`. + * An empty sub-folder named `"SubFolderAlreadyExists2"`. + * A file named `"File2.txt"`. + * A file named `"FileAlreadyExists2.txt"`. +* `"C:\Destination"` already contains: + * A folder named `"SubFolderAlreadyExists1"`. + * A folder named `"SubFolderAlreadyExists2"`. + * A file named `"FileAlreadyExists1.txt"`. + * A file named `"FileAlreadyExists2.txt"`. + +Therefore, overwrite must be set to `true` to ensure the existing folders and files can be overwritten. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Paths][FolderPaths Property] | `($)FolderPaths`, with value `[@"C:\Source\Folder1", @"C:\Source\Folder2"]` | `($)FolderPaths` is a variable of type [IEnumerable][]<[String][]> | +| [Destination Path][DestinationPath Property] | `($)DestinationPath`, with value `@"C:\Destination"` | `($)DestinationPath` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Content Only][ContentOnly Property] | `($)ContentOnly`, with value `true` | `($)ContentOnly` is a variable of type [Boolean][] | + +#### Result + +Moving `["C:\Source\Folder1", "C:\Source\Folder2"]` content only to `"C:\Destination"` with the [Overwrite][Overwrite Property] option set to `true`, and where `"C:\Destination\SubFolderAlreadyExists1"`, `"C:\Destination\SubFolderAlreadyExists2"`, `"C:\Destination\FileAlreadyExists1.txt"` and `"C:\Destination\FileAlreadyExists2.txt"` already exist will: + +* Move `"C:\Source\Folder1\SubFolder1"` to `"C:\Destination\SubFolder1"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists1"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder1\File1.txt"` to `"C:\Destination\File1.txt"` with: + * The content copied left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists1.txt"` with: + * The content copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Created` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder1\FileAlreadyExists1.txt"`. +* Move `"C:\Source\Folder2\SubFolder2"` to `"C:\Destination\SubFolder2"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Overwrite the existing folder at `"C:\Destination\SubFolderAlreadyExists2"` with: + * The content left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* Move `"C:\Source\Folder2\File2.txt"` to `"C:\Destination\File2.txt"` with: + * The content copied left unchanged. + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [File attributes][] left unchanged. +* Overwrite the existing file at `"C:\Destination\FileAlreadyExists2.txt"` with: + * The content copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Created` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Accessed` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The `Date Modified` copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + * The [File attributes][] copied from `"C:\Source\Folder2\FileAlreadyExists2.txt"`. + +*** + +### Move folders and their content to the same location but with a different name + +If it is required to move folders and their content into the same folder they are currently located in, but with a different name, then it is not possible to do with this block; the [Rename Folder][] block must be used instead. + +*** + +### Move folders and their content to a different location but with a different name + +If it is required to move folders and their content into a different folder than the one they are currently located in, but with a different name, it is not possible to do with a single block; you must use a combination of this block and the [Rename Folder][] block. + +*** + +## Properties + +### Folder Paths + +The [Folder Paths][FolderPaths Property] to move the folders and/or their content from. + +Each folder path in [Folder Paths][FolderPaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPaths` with no value | + +### Destination Path + +The [Destination Path][DestinationPath Property] to move the folders and/or their content to. + +The [Destination Path][DestinationPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +The [Destination Path][DestinationPath Property] must point to a folder, otherwise an [InvalidPathException][] will be thrown. + +The moved folders and files will have the same names as the folders and files copied. + +Any non-existing folders within the [Destination Path][DestinationPath Property] will be automatically created. + +For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the folders and/or contents being moved to in the [Destination Path][DestinationPath Property] if they already exist. + +If any of the folders and/or contents exists, [Overwrite][Overwrite Property] must be set to `true`, otherwise an [OperationFailedException][] will be thrown. By default, this is set to `false` to avoid implicit and accidental overwriting of existing folders and files. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Content Only + +Option to specify whether to move the folders and their content or just the [Content Only][ContentOnly Property]. + +To move the folders and their content, [Content Only][ContentOnly Property] must be set to `false`; to move just the content, [Content Only][ContentOnly Property] must be set to `true`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPathException][] | The [Destination Path][DestinationPath Property] points to a file. | +| | The [Destination Path][DestinationPath Property] contains leading spaces. | +| | The [Destination Path][DestinationPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Destination Path][DestinationPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | Any folder path in [Folder Paths][FolderPaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty Folder Paths][]| +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. For more information, see [Duplicate Folder Paths][] | +| | Any folder path in [Folder Paths][FolderPaths Property] does not exist. | +| | Any folder path in [Folder Paths][FolderPaths Property] points to a file. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains leading spaces. | +| | Any folder path in [Folder Paths][FolderPaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | Any folder path in [Folder Paths][FolderPaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any folder path in [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | Any folder path in [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] is invalid (for example, it is on an unmapped drive). | +| | Any folder path in [Folder Paths][FolderPaths Property] and [Destination Path][DestinationPath Property] point to the same folder and [Content Only][ContentOnly Property] is `true`. | +| | Any folder path in [Folder Paths][FolderPaths Property] is a child folder in the [Destination Path][DestinationPath Property] and [Content Only][ContentOnly Property] is `false`. | +| | Any file being moved already exists in the specified [Destination Path][DestinationPath Property] and overwrite is `false`. | +| | Any file being moved already exists in the specified [Destination Path][DestinationPath Property], is read-only and overwrite is `true`. | +| | The user the flow is executing as does not have the required permissions to move the folder or any of its content (e.g. not having read access to any of the folders in [Folder Paths][FolderPaths Property] or its content, or write access to the [Destination Path][DestinationPath Property]). | +| | The operation is cyclic (e.g. moving a folder into one of its sub-folders). | +| | An unexpected error occurs when moving a folder or any of its content. | +| [PropertyEmptyException][] | Thrown when [Folder Paths][FolderPaths Property] does not contain any items, or [Destination Path][DestinationPath Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Paths][FolderPaths Property] or [Destination Path][DestinationPath Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path and Destination Path need escaping + +Each folder paths in [Folder Paths][FolderPaths Property] and [Destination Path][DestinationPath Property] require `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the folder path (e.g. `@"C:\Source"`) and [Destination Path][DestinationPath Property] (e.g. `@"C:\Destination"`). + +### Folder Attributes + +When moving the folders at the specified [Folder Paths][FolderPaths Property] or any folder under them to the new [Destination Path][DestinationPath Property], if the folder already exists in the destination its attributes remain unchanged. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### File Attributes + +When moving a file under any of the [Folder Paths][FolderPaths Property] to the new [Destination Path][DestinationPath Property], all of the file's attributes are also moved. + +For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +### Conflicting Content + +If two or more paths in the specified [Folder Paths][FolderPaths Property] contain content (folders or files) with the same name, and [Overwrite][Overwrite Property] and [Content Only][ContentOnly Property] are `true`: + +* The attributes of the folder/file in the [Destination Path][DestinationPath Property] will be that of the first one moved. +* For files, the content of the file in the [Destination Path][DestinationPath Property] will be that of the last one moved. + +### Handling of Exceptions + +If an exception occurs when trying to move a folder in [Folder Paths][FolderPaths Property], it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +[FolderPaths Property]: {{< ref "#folder-paths" >}} +[DestinationPath Property]: {{< ref "#destination-path" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[ContentOnly Property]: {{< ref "#content-only" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} +[File Attributes]: {{< ref "#file-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidPathException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidPathException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty Folder Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/_index.md new file mode 100644 index 000000000..172a52744 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Read File" +linkTitle: "Read File" +description: "Read the content of a file." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-lines-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-lines-block.md new file mode 100644 index 000000000..b67d546b1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-lines-block.md @@ -0,0 +1,178 @@ +--- +title: "Read All Lines" +linkTitle: "Read All Lines" +description: "Reads all lines from a file at the specified file path." +--- + +{{< figure src="/blocks/files-read-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.ReadFile.ReadAllLinesBlock)
+ +## Description + +Reads all [Lines][Lines Property] from a file at the specified [File Path][FilePath Property], with an option to explicitly specify the [Encoding][Encoding Property] of the file if needed. + +## Examples + +### Read all lines + +This example will read all lines from `"C:\Source\File.txt"`, automatically detecting the encoding. + +In this example assume `"C:\Source\File.txt"` is a UTF-8 encoded file containing 10 lines: + +```plaintext +This is Line 1 +This is Line 2 +This is Line 3 +This is Line 4 +This is Line 5 +This is Line 6 +This is Line 7 +This is Line 8 +This is Line 9 +This is Line 10 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Lines][Lines Property] | `($)Lines`, with no value | `($)Lines` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Reading all lines from `"C:\Source\File.txt"` results in the variable `($)Lines` being updated to the following: + +```json +[ + "This is Line 1", + "This is Line 2", + "This is Line 3", + "This is Line 4", + "This is Line 5", + "This is Line 6", + "This is Line 7", + "This is Line 8", + "This is Line 9", + "This is Line 10" +] +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to read all lines of the file from. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to read the file. + +Most of the time [Encoding][Encoding Property] can be left as `null`; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned [Lines][Lines Property] are not in the correct format because the block was unable to detect the encoding of the file, it is possible to specify the [Encoding][Encoding Property] explicitly using this property. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Lines + +All [Lines][Lines Property] that were read from the file. + +A line is defined as a sequence of characters followed by a carriage return (i.e. `\r`), a line feed (i.e. `\n`), or a carriage return immediately followed by a line feed. The resulting [Lines][Lines Property] do not contain the terminating carriage returns and/or line feeds. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Lines` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | The [File Path][FilePath Property] does not exist. | +| | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to read the file. | +| | An unexpected error occurs when reading the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +[FilePath Property]: {{< ref "#file-path" >}} +[Encoding Property]: {{< ref "#encoding" >}} +[Lines Property]: {{< ref "#lines" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-text-block.md new file mode 100644 index 000000000..15e3e33d1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/read-file/read-all-text-block.md @@ -0,0 +1,173 @@ +--- +title: "Read All Text" +linkTitle: "Read All Text" +description: "Reads all text from a file at the specified file path." +--- + +{{< figure src="/blocks/files-read-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.ReadFile.ReadAllTextBlock)
+ +## Description + +Reads all [Text][Text Property] from a file at the specified [File Path][FilePath Property], with an option to explicitly specify the [Encoding][Encoding Property] of the file if needed. + +## Examples + +### Read all text + +This example will read all text from `"C:\Source\File.txt"`, automatically detecting the encoding. + +In this example assume `"C:\Source\File.txt"` is a UTF-8 encoded file containing the following text: + +```plaintext +This is Line 1 +This is Line 2 +This is Line 3 +This is Line 4 +This is Line 5 +This is Line 6 +This is Line 7 +This is Line 8 +This is Line 9 +This is Line 10 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] | + +#### Result + +Reading all text from `"C:\Source\File.txt"` results in the variable `($)Text` being updated to the following: + +```json +"This is Line 1 +This is Line 2 +This is Line 3 +This is Line 4 +This is Line 5 +This is Line 6 +This is Line 7 +This is Line 8 +This is Line 9 +This is Line 10" +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to read all text of the file from. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to read the file. + +Most of the time [Encoding][Encoding Property] can be left as `null`; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned [Text][Text Property] are not in the correct format because the block was unable to detect the encoding of the file, it is possible to specify the [Encoding][Encoding Property] explicitly using this property. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Text + +All [Text][Text Property] that was read from the file. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | The [File Path][FilePath Property] does not exist. | +| | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to read the file. | +| | An unexpected error occurs when reading the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +[FilePath Property]: {{< ref "#file-path" >}} +[Encoding Property]: {{< ref "#encoding" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/_index.md new file mode 100644 index 000000000..e4b6c16b7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/_index.md @@ -0,0 +1,5 @@ +--- +title: "Rename Folder" +linkTitle: "Rename Folder" +description: "Rename a folder." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/rename-folder-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/rename-folder-block.md new file mode 100644 index 000000000..b3a86a7b4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/rename-folder/rename-folder-block.md @@ -0,0 +1,158 @@ +--- +title: "Rename Folder" +linkTitle: "Rename Folder" +description: "Renames a folder at the specified folder path to a new name." +--- + +{{< figure src="/blocks/folders-rename-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.RenameFolder.RenameFolderBlock)
+ +## Description + +Renames a folder at the specified [Folder Path][FolderPath Property] to a [New Name][NewName Property]. + +## Examples + +### Rename a folder + +This example will rename `"C:\Source\Folder"` to `"C:\Source\RenamedFolder"`. + +In this example assume: + +* `"C:\Source\Folder"` contains: + * An empty sub-folder named `"SubFolder"`. + * A file named `"File.txt"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Folder Path][FolderPath Property] | `($)FolderPath`, with value `@"C:\Source\Folder"` | `($)FolderPath` is a variable of type [String][] | +| [New Name][NewName Property] | `($)NewName`, with value `"RenamedFolder"` | `($)NewName` is a variable of type [String][] | + +#### Result + +Renaming `"C:\Source\Folder"` to `"RenamedFolder"` will: + +* Rename the existing folder at `"C:\Source\Folder"` to `"C:\Source\RenamedFolder"` with: + * The `Date Created` left unchanged. + * The `Date Accessed` left unchanged. + * The `Date Modified` left unchanged. + * The [Folder attributes][] left unchanged. +* `"SubFolder"` and `"File.txt"` will be located under `"C:\Source\RenamedFolder"` and their names, dates, attributes and content will be left unchanged. + +*** + +### Other Move Operations + +If any other folder move operation is required, the [Move Folder][] or [Move Folders][] blocks must be used instead. + +*** + +## Properties + +### Folder Path + +The [Folder Path][FolderPath Property] of the folder to rename. + +The [Folder Path][FolderPath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FolderPath` with no value | + +### New Name + +The [New Name][NewName Property] to rename the folder to. + +The [New Name][NewName Property] is case-insensitive and any trailing spaces will be automatically removed. + +The [New Name][NewName Property] must be a valid folder name, otherwise an [InvalidFolderNameException][] will be thrown. + +For information about valid folder names, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidFolderNameException][] | A folder or file with the [New Name][NewName Property] already exists. | +| | The [New Name][NewName Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`). | +| | The [New Name][NewName Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| [OperationFailedException][] | The [Folder Path][FolderPath Property] does not exist. | +| | The [Folder Path][FolderPath Property] points to a file. | +| | The [Folder Path][FolderPath Property] contains leading spaces. | +| | The [Folder Path][FolderPath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any folder names. | +| | The [Folder Path][FolderPath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [Folder Path][FolderPath Property] is a win32 device path (i.e starts with a `"\\.\"`). | +| | The [Folder Path][FolderPath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to rename the folder or any of its content (e.g. not having read access to the [Folder Path][FolderPath Property] or its content, or write access to the parent of [Folder Path][FolderPath Property]. | +| | An unexpected error occurs when renaming the folder. | +| [PropertyEmptyException][] | Thrown when [Folder Path][FolderPath Property] or [New Name][NewName Property] are empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Folder Path][FolderPath Property] or [New Name][NewName Property] are `null`. | + +## Remarks + +### Folder Paths + +For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### Folder Path needs escaping + +[Folder Path][FolderPath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\"`), or +* Prepending an `@` character before the start of the [Folder Path][FolderPath Property] (e.g. `@"C:\Source"`). + +### Folder Attributes + +When renaming the folder at the specified [Folder Path][FolderPath Property] all of the folder's attributes are left unchanged. + +For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see [File & Folder Attributes][]. + +[FolderPath Property]: {{< ref "#folder-path" >}} +[NewName Property]: {{< ref "#new-name" >}} + +[Folder Attributes]: {{< ref "#folder-attributes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[InvalidFolderNameException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.InvalidFolderNameException.MainDoc" >}} +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Attributes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Attributes.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[Move Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolder.MainDoc" >}} +[Move Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolders.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/_index.md new file mode 100644 index 000000000..5bdc44c30 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Search File(s)" +linkTitle: "Search File(s)" +description: "Search a file or multiple files." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-file-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-file-block.md new file mode 100644 index 000000000..9738bf1d3 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-file-block.md @@ -0,0 +1,406 @@ +--- +title: "Search File" +linkTitle: "Search File" +description: "Searches a file at a specified file path for a matching search pattern." +--- + +{{< figure src="/blocks/files-search-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.SearchFile.SearchFileBlock)
+ +## Description + +Searches the file at the specified [File Path][FilePath Property] for text that matches a given [Search Pattern][SearchPattern Property]. + +Results are returned as a list of [Matches][Matches Property]. + +Additional options can be specified: + +* [Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search. +* [Encoding][Encoding Property] can be specified if needed to explicitly state the encoding that should be used to read and search the file. +* A [Comparison Type][ComparisonType Property] option can specified to choose how it is determined whether text matches the [Search Pattern][SearchPattern Property] (e.g. whether the search is case-sensitive or case-insensitive). + +## Examples + +### Get matches for a given text + +This example will get all matches in the file `"C:\Source\File.txt"` that match the text `"error"`. + +It will perform a case-insensitive search, and let the block determine the encoding of the file automatically. + +In this example assume `"C:\Source\File.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"error"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IList][]<[FileMatch][]> value | + +#### Result + +Searching `"C:\Source\File.txt"` for all text matching `"error"` (case-insensitive), results in the variable `($)Matches` being updated to the following: + +```json +[ + { + "FilePath": "C:\\Source\\File.txt", + "Line": 1, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File.txt", + "Line": 4, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File.txt", + "Line": 4, + "Value": "error", + "Index": 19, + "Length": 5, + "Groups": {} + } +] +``` + +*** + +### Get matches for a given pattern + +This example will get all matches in the file `"C:\Source\File.txt"` that match the pattern `"Uptime is * hours."`. + +It will perform a case-sensitive search, and let the block determine the encoding of the file automatically. + +In this example assume `"C:\Source\File.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"Uptime is * hours."` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IList][]<[FileMatch][]> value | + +#### Result + +Searching `"C:\Source\File.txt"` for all text matching the pattern `"Uptime is * hours."` (case-sensitive), results in the variable `($)Matches` being updated to the following: + +```json +[ + { + "FilePath": "C:\\Source\\File.txt", + "Line": 2, + "Value": "Uptime is 2 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File.txt", + "Line": 3, + "Value": "Uptime is 3 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + } +] +``` + +*** + +### Get matches for a given regex + +This example will get all matches in the file `"C:\Source\File.txt"` that match the regex `"^Error:.*$"`. + +It will perform a case-sensitive search, explicitly specify the encoding of the file as UTF-8 and will match any line that starts with `"Error:"`. + +In this example assume `"C:\Source\File.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"^Error:.*$"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `Encoding.UTF8` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IList][]<[FileMatch][]> value | + +#### Result + +Searching `"C:\Source\File.txt"` for all text matching the regex `"^Error:.*$"` (case-sensitive), results in the variable `($)Matches` being updated to the following: + +```json +[ + { + "FilePath": "C:\\Source\\File.txt", + "Line": 1, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File.txt", + "Line": 4, + "Value": "Error: An terminal error has occurred. The service will restart now.", + "Index": 0, + "Length": 68, + "Groups": {} + } +] +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to search for text that matches a given [Search Pattern][SearchPattern Property]. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Search Pattern + +The [Search Pattern][SearchPattern Property] which text must match to be included in the returned [Matches][Matches Property]. + +A `null` or empty (i.e. `""`) [Search Pattern][SearchPattern Property] means match anything; all additional block options such as [Search Options][SearchOptions Property] etc. still take effect. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Search Pattern][SearchPattern Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to read and search the file. + +Most of the time [Encoding][Encoding Property] can be left as `null`; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned [Matches][Matches Property] are not correct because the block was unable to detect the encoding of the file, it is possible to specify the [Encoding][Encoding Property] explicitly using this property. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match text against the given [Search Pattern][SearchPattern Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Matches + +[Matches][Matches Property] containing a [FileMatch][] for every text that matches the specified [Search Pattern][SearchPattern Property] based on the other specified options. + +A basic example with a single [FileMatch][] can be seen below: + +```json +[ + { + "FilePath": "C:\\Source\\File.txt", + "Line": 1, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + } +] +``` + +For more information see the [example][] above, or the [FileMatch][] data type. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[FileMatch][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Matches` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | The [File Path][FilePath Property] does not exist. | +| | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to search the [File Path][FilePath Property]. | +| | An unexpected error occurs when searching the [File Path][FilePath Property]. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | +| [RegexMatchTimeoutException][] | Thrown when using [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and the [Search Pattern][SearchPattern Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### Null or empty Search Pattern + +A `null` or empty (i.e. `""`) [Search Pattern][SearchPattern Property] means match anything; all additional block options such as [Search Options][SearchOptions Property] etc. still take effect. + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Known Limitations + +* The text in the file at the specified [File Path][FilePath Property] is searched line-by-line. As a result, when using `SearchOptions.Regex` the in-line `s` regex character is not supported. +* If the text in the file at the specified [File Path][FilePath Property] ends with a blank line (`0` length) that line will not be read and therefore not matched against. +* If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[FilePath Property]: {{< ref "#file-path" >}} +[SearchPattern Property]: {{< ref "#search-pattern" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[Encoding Property]: {{< ref "#encoding" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Matches Property]: {{< ref "#matches" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[Example]: {{< ref "#get-matches-for-a-given-text" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[FileMatch]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FileMatch.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md new file mode 100644 index 000000000..eedddd278 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md @@ -0,0 +1,529 @@ +--- +title: "Search Files" +linkTitle: "Search Files" +description: "Searches files at the specified file paths for a matching search pattern." +--- + +{{< figure src="/blocks/files-search-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.SearchFile.SearchFilesBlock)
+ +## Description + +Searches the files at the specified [File Paths][FilePaths Property] for text that matches a given [Search Pattern][SearchPattern Property]. + +Results are returned as [Matches][Matches Property]. + +Additional options can be specified: + +* [Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search. +* [Encoding][Encoding Property] can be specified if needed to explicitly state the encoding that should be used to read and search the files. +* A [Comparison Type][ComparisonType Property] option can specified to choose how it is determined whether text matches the [Search Pattern][SearchPattern Property] (e.g. whether the search is case-sensitive or case-insensitive). + +## Examples + +### Get matches for a given text + +This example will get all matches in the files `["C:\Source\File1.txt", "C:\Source\File2.txt"]` that match the text `"error"`. + +It will perform a case-insensitive search, and let the block determine the encoding of the files automatically. + +In this example assume `"C:\Source\File1.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +and `"C:\Source\File2.txt"` contains the following text: + +```plaintext +Information: Uptime is 1 hour. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: Failed to determine uptime. +Error: Failed to determine uptime. +Information: Uptime is 6 hours. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\File1.txt", @"C:\Source\File2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable]<[String][]> | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"error"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IDictionary][]<[String][], [IList][]<[FileMatch][]>> value | + +#### Result + +Searching `"C:\Source\File.txt"` for all text matching `"error"` (case-insensitive), results in the variable `($)Matches` being updated to the following: + +```json +{ + "C:\\Source\\File1.txt" : [ + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 1, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 4, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 4, + "Value": "error", + "Index": 19, + "Length": 5, + "Groups": {} + } + ], + "C:\\Source\\File2.txt" : [ + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 4, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 5, + "Value": "Error", + "Index": 0, + "Length": 5, + "Groups": {} + } + ] +} +``` + +*** + +### Get matches for a given pattern + +This example will get all matches in the files `["C:\Source\File1.txt", "C:\Source\File2.txt"]` that match the pattern `"Uptime is * hour?."`. + +It will perform a case-sensitive search, and let the block determine the encoding of the files automatically. + +In this example assume `"C:\Source\File1.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +and `"C:\Source\File2.txt"` contains the following text: + +```plaintext +Information: Uptime is 1 hour. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: Failed to determine uptime. +Error: Failed to determine uptime. +Information: Uptime is 6 hours. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\File1.txt", @"C:\Source\File2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable]<[String][]> | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"Uptime is * hour?."` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IDictionary][]<[String][], [IList][]<[FileMatch][]>> value | + +#### Result + +Searching the files `["C:\Source\File1.txt", "C:\Source\File2.txt"]` for all text matching the pattern `"Uptime is * hour?."` (case-sensitive), results in the variable `($)Matches` being updated to the following: + +```json +{ + "C:\\Source\\File1.txt" : [ + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 2, + "Value": "Uptime is 2 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 3, + "Value": "Uptime is 3 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + } + ], + "C:\\Source\\File2.txt" : [ + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 1, + "Value": "Uptime is 1 hour.", + "Index": 13, + "Length": 17, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 2, + "Value": "Uptime is 2 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 3, + "Value": "Uptime is 3 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 6, + "Value": "Uptime is 6 hours.", + "Index": 13, + "Length": 18, + "Groups": {} + } + ] +} +``` + +*** + +### Get matches for a given regex + +This example will get all matches in the files `["C:\Source\File1.txt", "C:\Source\File2.txt"]` that match the regex `"^Error:.*$"`. + +It will perform a case-sensitive search, explicitly specify the encoding of the files as UTF-8 and will match any lines that start with `"Error:"`. + +In this example assume `"C:\Source\File1.txt"` contains the following text: + +```plaintext +Error: Failed to determine uptime. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: An terminal error has occurred. The service will restart now. +``` + +and `"C:\Source\File2.txt"` contains the following text: + +```plaintext +Information: Uptime is 1 hour. +Information: Uptime is 2 hours. +Information: Uptime is 3 hours. +Error: Failed to determine uptime. +Error: Failed to determine uptime. +Information: Uptime is 6 hours. +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Paths][FilePaths Property] | `($)FilePaths`, with value `[@"C:\Source\File1.txt", @"C:\Source\File2.txt"]` | `($)FilePaths` is a variable of type [IEnumerable]<[String][]> | +| [Search Pattern][SearchPattern Property] | `($)SearchPattern`, with value `"^Error:.*$"` | `($)SearchPattern` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `Encoding.UTF8` | `($)Encoding` is a variable of type [Encoding][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [IDictionary][]<[String][], [IList][]<[FileMatch][]>> value | + +#### Result + +Searching the files `["C:\Source\File1.txt", "C:\Source\File2.txt"]` for all text matching the regex `"^Error:.*$"` (case-sensitive), results in the variable `($)Matches` being updated to the following: + +```json +{ + "C:\\Source\\File1.txt" : [ + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 1, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 4, + "Value": "Error: An terminal error has occurred. The service will restart now.", + "Index": 0, + "Length": 68, + "Groups": {} + } + ], + "C:\\Source\\File2.txt" : [ + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 4, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + }, + { + "FilePath": "C:\\Source\\File2.txt", + "Line": 5, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + } + ] +} +``` + +*** + +## Properties + +### File Paths + +The [File Paths][FilePaths Property] to search for text that matches a given [Search Pattern][SearchPattern Property]. + +Each file path in [File Paths][FilePaths Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePaths` with no value | + +### Search Pattern + +The [Search Pattern][SearchPattern Property] which text must match to be included in the returned [Matches][Matches Property]. + +A `null` or empty (i.e. `""`) [Search Pattern][SearchPattern Property] means match anything; all additional block options such as [Search Options][SearchOptions Property] etc. still take effect. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `""`) | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Search Pattern][SearchPattern Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to read and search the files. + +Most of the time [Encoding][Encoding Property] can be left as `null`; allowing the block to automatically attempt to detect the encoding of the files based on the presence of byte order marks. However, if it is found that the returned [Matches][Matches Property] are not correct because the block was unable to detect the encoding of the files, it is possible to specify the [Encoding][Encoding Property] explicitly using this property. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match text against the given [Search Pattern][SearchPattern Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Matches + +[Matches][Matches Property] containing an entry for each file in [File Paths][FilePaths Property]. + +The key of each entry is the file path, and the value contains a [FileMatch][] for every text in the file path that matches the specified [Search Pattern][SearchPattern Property] based on the other specified options. + +A basic example with a single file path and a single [FileMatch][] can be seen below: + +```json +{ + "C:\\Source\\File1.txt" : [ + { + "FilePath": "C:\\Source\\File1.txt", + "Line": 1, + "Value": "Error: Failed to determine uptime.", + "Index": 0, + "Length": 34, + "Groups": {} + } + ] +} +``` + +For more information see the [example][] above, or the [FileMatch][] data type. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][]<[String][], [IList][]<[FileMatch][]>> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Matches` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | Any file path in [File Paths][FilePaths Property] is `null` or empty (i.e. `""`). For more information, see [Null or Empty File Paths][]| +| | Any file path in [File Paths][FilePaths Property] is duplicated. For more information, see [Duplicate File Paths][] | +| | Any file path in [File Paths][FilePaths Property] does not exist. | +| | Any file path in [File Paths][FilePaths Property] points to a folder. | +| | Any file path in [File Paths][FilePaths Property] contains leading spaces. | +| | Any file path in [File Paths][FilePaths Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | Any file path in [File Paths][FilePaths Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | Any file path in [File Paths][FilePaths Property] is invalid (for example, it is on an unmapped drive). | +| | The user the flow is executing as does not have the required permissions to search a file path in [File Paths][FilePaths Property]. | +| | An unexpected error occurs when searching any file path in [File Paths][FilePaths Property]. | +| [PropertyEmptyException][] | Thrown when [File Paths][FilePaths Property] does not contain any items. | +| [PropertyNullException][] | Thrown when [File Paths][FilePaths Property] is `null`. | +| [RegexMatchTimeoutException][] | Thrown when using [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and the [Search Pattern][SearchPattern Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Paths needs escaping + +Each file path in [File Paths][FilePaths Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Paths][FilePaths Property] (e.g. `@"C:\Source\File.txt"`). + +### Null or empty Search Pattern + +A `null` or empty (i.e. `""`) [Search Pattern][SearchPattern Property] means match anything; all additional block options such as [Search Options][SearchOptions Property] etc. still take effect. + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Handling of Exceptions + +If an exception occurs when trying to search a file in the [File Paths][FilePaths Property], it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an [OperationFailedException][]. + +### Known Limitations + +* The text in the files at the specified [File Paths][FilePaths Property] is searched line-by-line. As a result, when using `SearchOptions.Regex` the in-line `s` regex character is not supported. +* If the text in the files at the specified [File Paths][FilePaths Property] ends with a blank line (`0` length) that line will not be read and therefore not matched against. +* If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[FilePaths Property]: {{< ref "#file-paths" >}} +[SearchPattern Property]: {{< ref "#search-pattern" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[Encoding Property]: {{< ref "#encoding" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Matches Property]: {{< ref "#matches" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[Duplicate File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfDuplicatePaths" >}} +[Null Or Empty File Paths]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.IndexesOfNullOrEmptyPaths" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[Example]: {{< ref "#get-matches-for-a-given-text" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[FileMatch]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FileMatch.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/_index.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/_index.md new file mode 100644 index 000000000..bcadbe7f5 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/_index.md @@ -0,0 +1,5 @@ +--- +title: "Write File" +linkTitle: "Write File" +description: "Write the content of a file." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-lines-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-lines-block.md new file mode 100644 index 000000000..e83c5026e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-lines-block.md @@ -0,0 +1,226 @@ +--- +title: "Write All Lines" +linkTitle: "Write All Lines" +description: "Writes all specified lines to a file at the given file path." +--- + +{{< figure src="/blocks/files-write-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.WriteFile.WriteAllLinesBlock)
+ +## Description + +Writes all specified [Lines][Lines Property] to the end of the file at the given [File Path][FilePath Property], with an option to explicitly specify the [Encoding][Encoding Property] to write the file as if needed. + +An option can also be specified to [Overwrite][Overwrite Property] rather than append to the file. + +## Examples + +### Write all lines, appending to the end of the file + +This example will append `["New Line 1", "New Line 2"]` to `"C:\Source\File.txt"`, using UTF-8 encoding without a byte order mark. + +In this example assume `"C:\Source\File.txt"` contains 2 lines: + +```plaintext +Original Line 1 +Original Line 2 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Lines][Lines Property] | `($)Lines`, with value `["New Line 1", "New Line 2"]` | `($)Lines` is a variable of type [IEnumerable][]<[String][]> | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | + +#### Result + +Writing `["New Line 1", "New Line 2"]` to `"C:\Source\File.txt"` results in the content being updated to the following: + +```plaintext +Original Line 1 +Original Line 2 +New Line 1 +New Line 2 +``` + +*** + +### Write all lines, overwriting the file content + +This example will overwrite the content of `"C:\Source\File.txt"` with `["New Line 1", "New Line 2"]`, using UTF-8 encoding without a byte order mark. + +In this example assume `"C:\Source\File.txt"` contains 2 lines: + +```plaintext +Original Line 1 +Original Line 2 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Lines][Lines Property] | `($)Lines`, with value `["New Line 1", "New Line 2"]` | `($)Lines` is a variable of type [IEnumerable][]<[String][]> | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | + +#### Result + +Overwriting `"C:\Source\File.txt"` with `["New Line 1", "New Line 2"]` results in the content being updated to the following: + +```plaintext +New Line 1 +New Line 2 +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to write all [Lines][Lines Property] to. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +If the file does not exist at the [File Path][FilePath Property], a new file is created, and any non-existing folders will also be created. + +If the file already exists at the [File Path][FilePath Property] and [Overwrite][Overwrite Property] is: + +* `true`, the [Lines][Lines Property] overwrite the existing file content. +* `false`, the [Lines][Lines Property] are appended to the existing file content. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Lines + +The [Lines][Lines Property] to write to the file. + +[Lines][Lines Property] can be `null` or empty (i.e. `""`). + +If [Lines][Lines Property] is `null` or empty (i.e. `""`) and [Overwrite][Overwrite Property] is: + +* `true`, a blank file will be written. +* `false`, nothing is written. + +If [Lines][Lines Property] contains an entry that is `null` or empty (i.e. `""`) a blank line will be written for that entry. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Lines` with no value | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the file content with the [Lines][Lines Property], rather than appending them. + +By default, this is set to `false` to avoid implicit and accidental overwriting of the file content. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to write the file. + +If the [Encoding][Encoding Property] is left as `null`, the [Lines][Lines Property] will be written using UTF-8 encoding without a byte order mark. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The file at the specified [File Path][FilePath Property] is hidden or is a System file, and overwrite is `true`. | +| | The file at the specified [File Path][FilePath Property] is a read-only file. | +| | The user the flow is executing as does not have the required permissions to write to the file. | +| | An unexpected error occurs when writing the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +[FilePath Property]: {{< ref "#file-path" >}} +[Lines Property]: {{< ref "#lines" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[Encoding Property]: {{< ref "#encoding" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-text-block.md new file mode 100644 index 000000000..4b9ebd6b4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Files-And-Folders/write-file/write-all-text-block.md @@ -0,0 +1,223 @@ +--- +title: "Write All Text" +linkTitle: "Write All Text" +description: "Writes all specified text to a file at the given file path." +--- + +{{< figure src="/blocks/files-write-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.FilesAndFolders.WriteFile.WriteAllTextBlock)
+ +## Description + +Writes all specified [Text][Text Property] to the end of the file at the given [File Path][FilePath Property], with an option to explicitly specify the [Encoding][Encoding Property] to write the file as if needed. + +An option can also be specified to [Overwrite][Overwrite Property] rather than append to the file. + +## Examples + +### Write all text, appending to the end of the file + +This example will append `"New Line 1\r\nNew Line 2"` to `"C:\Source\File.txt"`, using UTF-8 encoding without a byte order mark. + +In this example assume `"C:\Source\File.txt"` contains the following text: + +```plaintext +Original Line 1 +Original Line 2 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Text][Text Property] | `($)Text`, with value `"New Line 1\r\nNew Line 2"` | `($)Text` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `false` | `($)Overwrite` is a variable of type [Boolean][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | + +#### Result + +Writing `"New Line 1\r\nNew Line 2"` to `"C:\Source\File.txt"` results in the content being updated to the following: + +```plaintext +Original Line 1 +Original Line 2 +New Line 1 +New Line 2 +``` + +*** + +### Write all text, overwriting the file content + +This example will overwrite the content of `"C:\Source\File.txt"` with `"New Line 1\r\nNew Line 2"`, using UTF-8 encoding without a byte order mark. + +In this example assume `"C:\Source\File.txt"` contains the following text: + +```plaintext +Original Line 1 +Original Line 2 +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [File Path][FilePath Property] | `($)FilePath`, with value `@"C:\Source\File.txt"` | `($)FilePath` is a variable of type [String][] | +| [Text][Text Property] | `($)Text`, with value `"New Line 1\r\nNew Line 2"` | `($)Text` is a variable of type [String][] | +| [Overwrite][Overwrite Property] | `($)Overwrite`, with value `true` | `($)Overwrite` is a variable of type [Boolean][] | +| [Encoding][Encoding Property] | `($)Encoding`, with value `null` | `($)Encoding` is a variable of type [Encoding][] | + +#### Result + +Overwriting `"C:\Source\File.txt"` with `"New Line 1\r\nNew Line 2"` results in the content being updated to the following: + +```plaintext +New Line 1 +New Line 2 +``` + +*** + +## Properties + +### File Path + +The [File Path][FilePath Property] to write the [Text][Text Property] to. + +The [File Path][FilePath Property] is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed. + +If the file does not exist at the [File Path][FilePath Property], a new file is created, and any non-existing folders will also be created. + +If the file already exists at the [File Path][FilePath Property] and [Overwrite][Overwrite Property] is: + +* `true`, the [Text][Text Property] overwrites the existing file content. +* `false`, the [Text][Text Property] is appended to the existing file content. + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see [File & Folder Paths][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)FilePath` with no value | + +### Text + +The [Text][Text Property] to write to the file. + +[Text][Text Property] can be `null` or empty (i.e. `""`). + +If [Text][Text Property] is `null` or empty (i.e. `""`) and [Overwrite][Overwrite Property] is: + +* `true`, a blank file will be written. +* `false`, nothing is written. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Overwrite + +Option to [Overwrite][Overwrite Property] the file content with the [Text][Text Property], rather than appending it. + +By default, this is set to `false` to avoid implicit and accidental overwriting of the file content. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `false` | + +### Encoding + +Option to specify the [Encoding][Encoding Property] that should be used to write the file. + +If the [Encoding][Encoding Property] is left as `null`, the [Text][Text Property] will be written using UTF-8 encoding without a byte order mark. + +For information about encoding, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +| | | +|--------------------|---------------------------| +| Data Type | [Encoding][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Encoding][Encoding Property] is invalid (e.g. `Encoding.GetEncoding(-1)`). See [Value Is Invalid][]. | +| [OperationFailedException][] | The [File Path][FilePath Property] points to a folder. | +| | The [File Path][FilePath Property] contains leading spaces. | +| | The [File Path][FilePath Property] contains only whitespace, or the NUL character (i.e. `\0`), or contains one or more invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) in any file or folder names. | +| | The [File Path][FilePath Property] exceeds the system-defined maximum length (typically 32,767 characters). | +| | The [File Path][FilePath Property] is invalid (for example, it is on an unmapped drive). | +| | The file at the specified [File Path][FilePath Property] is hidden or is a System file, and overwrite is `true`. | +| | The file at the specified [File Path][FilePath Property] is a read-only file. | +| | The user the flow is executing as does not have the required permissions to write to the file. | +| | An unexpected error occurs when writing the file. | +| [PropertyEmptyException][] | Thrown when [File Path][FilePath Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [File Path][FilePath Property] is `null`. | + +## Remarks + +### File Paths + +For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see [File & Folder Paths][]. + +### File Path needs escaping + +[File Path][FilePath Property] requires `\` characters to be escaped, otherwise each unescaped `\` will be reported as an `Invalid property value` message when trying to debug the flow. + +Escaping can be done in two ways: + +* Escaping the `\` character with another `\` character (e.g. `"C:\\Source\\File.txt"`), or +* Prepending an `@` character before the start of the [File Path][FilePath Property] (e.g. `@"C:\Source\File.txt"`). + +### Encoding of text + +For information about encoding of text, examples of available encodings and using them, please see [Encoding][Working with Text - Encoding]. + +[FilePath Property]: {{< ref "#file-path" >}} +[Text Property]: {{< ref "#text" >}} +[Overwrite Property]: {{< ref "#overwrite" >}} +[Encoding Property]: {{< ref "#encoding" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Working with Text - Encoding]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Encoding.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[OperationFailedException]: {{< url path="Cortex.Reference.Exceptions.FilesAndFolders.OperationFailedException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Encoding]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/_index.md new file mode 100644 index 000000000..6e11b63ca --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Count(s) of Items" +linkTitle: "Get Count(s) of Items" +description: "Get the count(s) of items in a list." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-all-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-all-items-block-2.md new file mode 100644 index 000000000..1c31ce973 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-all-items-block-2.md @@ -0,0 +1,115 @@ +--- +title: "Get Count Of All Items" +linkTitle: "Get Count Of All Items" +description: "Gets the count of all items in a List." +--- + +{{< figure src="/blocks/lists-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetCount.GetCountOfAllItemsBlock`2)
+ +## Description + +Gets the [Count][Count Property] of all items in a [List][List Property]. + +## Examples + +### Get Count of all items in a List + +This example will get the count of all items in `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Count][Count Property] | `($)Count`, with no value | `($)Count` is a variable that will be set to an [Int32][] value | + +#### Result + +Getting the count of all items in `["Some Text", 1]` results in the variable `($)Count` being updated to the following: + +```json +2 +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Count][Count Property] of all items for. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Count + +The [Count][Count Property] of all items in [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Count][Count Property] property is set to `0`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Count Property]: {{< ref "#count" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-value-block-2.md new file mode 100644 index 000000000..209b5523e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-value-block-2.md @@ -0,0 +1,145 @@ +--- +title: "Get Count Of Items With Value" +linkTitle: "Get Count Of Items With Value" +description: "Gets the count of items in a List with the specified value." +--- + +{{< figure src="/blocks/lists-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetCount.GetCountOfItemsWithValueBlock`2)
+ +## Description + +Gets the [Count][Count Property] of items in a [List][List Property] with the specified [Value][Value Property]. + +## Examples + +### Get Count of items in a List with a Value + +This example will get the count of items in `["Some Text", 1]` with the value `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Count][Count Property] | `($)Count`, with no value | `($)Count` is a variable that will be set to an [Int32][] value | + +#### Result + +Getting the count of items in `["Some Text", 1]` with the value `1` results in the variable `($)Count` being updated to the following: + +```json +1 +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Count][Count Property] of items with the specified [Value][Value Property] for. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] items must match to be included in the [Count][Count Property]. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Count + +The [Count][Count Property] of items in [List][List Property] with the specified [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Count][Count Property] property is set to `0`. + +### No items matching Value + +If [List][List Property] does not contain items matching the specified [Value][Value Property], the variable specified in the [Count][Count Property] property is set to `0`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[Count Property]: {{< ref "#count" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-values-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-values-block-2.md new file mode 100644 index 000000000..256866b3c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-values-block-2.md @@ -0,0 +1,149 @@ +--- +title: "Get Counts Of Items With Values" +linkTitle: "Get Counts Of Items With Values" +description: "Gets the counts of items in a List matching each of the specified values." +--- + +{{< figure src="/blocks/lists-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetCount.GetCountsOfItemsWithValuesBlock`2)
+ +## Description + +Gets the [Counts][Counts Property] of items in a [List][List Property] matching each of the specified [Values][Values Property]. + +## Examples + +### Get Counts of items in a List matching each of the Values + +This example will get the counts of items in `["Some Text", 1]` matching each of the values `[1, 2, 3]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Counts][Counts Property] | `($)Counts`, with no value | `($)Counts` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +Getting the counts of items in `["Some Text", 1]` matching each of the values `[1, 2, 3]` results in the variable `($)Counts` being updated to the following: + +```json +[1, 0, 0] +``` + +The counts of items matching each value are added to `($)Counts` at the same [index][Indexes] the value is in `($)Values`. In this example, there is one item matching the first value `1`, zero items matching the second value `2` and zero items matching the third value `3`, resulting in `($)Counts` being set to `[1, 0, 0]`. + +*** + +## Properties + +### List + +The [List][List Property] to get the [Counts][Counts Property] of items matching each of the specified [Values][Values Property] for. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Values + +The [Values][Values Property] items must match to be included in the [Counts][Counts Property]. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Counts + +The [Counts][Counts Property] of items in [List][List Property] matching each of the specified [Values][Values Property]. + +For each value in [Values][Values Property], [Counts][Counts Property] will have a corresponding item whose value is the count of items in [List][List Property] matching the value. + +I.e. The count of items matching the first value in [Values][Values Property] will be saved as the first item in [Counts][Counts Property]; the count of items matching the second value in [Values][Values Property] will be saved as the second item in [Counts][Counts Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[Int32][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Counts` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] or [Values][Values Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`), the variable specified in the [Counts][Counts Property] property is set to empty (i.e. `[]`). + +### No items matching a specified value in Values + +If [List][List Property] does not contain items matching one of the specified [Values][Values Property], `0` is written to the corresponding item in [Counts][Counts Property] for that value. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Values Property]: {{< ref "#values" >}} +[Counts Property]: {{< ref "#counts" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/_index.md new file mode 100644 index 000000000..f76c2f371 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Index(es) of Items" +linkTitle: "Get Index(es) of Items" +description: "Get the index of an item or indexes of multiple items contained in a list." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-index-of-item-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-index-of-item-with-value-block-2.md new file mode 100644 index 000000000..15a2b1dac --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-index-of-item-with-value-block-2.md @@ -0,0 +1,207 @@ +--- +title: "Get Index Of Item With Value" +linkTitle: "Get Index Of Item With Value" +description: "Gets the index of the specified occurrence of an item in a List matching a value." +--- + +{{< figure src="/blocks/lists-get-index-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetIndex.GetIndexOfItemWithValueBlock`2)
+ +## Description + +Gets the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of an item in a [List][List Property] matching a [Value][Value Property]. + +## Examples + +### Get the Index of the first Occurrence of an item in a List matching a Value + +This example will attempt to get the index of the first occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means the first occurrence; `2` means second etc. + +Attempting to get the index of the first occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)Index` being updated to the following: + +```json +0 +``` + +*** + +### Get the Index of the last Occurrence of an item in a List matching a Value + +This example will attempt to get the index of the last occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means the last occurrence; `-2` means second last etc. + +Attempting to get the index of the last occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)List` being updated to the following: + +```json +5 +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of matching item from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the item to get the [Index][Index Property] of the specified [Occurrence][Occurrence Property] must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to get the [Index][Index Property] of. + +Items are considered matching if they have the specified [Value][Value Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Index + +[Int32][] indicating the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of item matching [Value][Value Property] in [List][List Property]. + +If there is no specified [Occurrence][Occurrence Property] of item matching [Value][Value Property] in [List][List Property], the specified variable will be set to `-1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Index` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Occurrences + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Index][Index Property] property is set to `-1`. + +### No items matching Value, or Occurrence is not present + +If [List][List Property] does not contain items matching the specified [Value][Value Property] or the specified [Occurrence][Occurrence Property] is not present, the variable specified in the [Index][Index Property] property is set to `-1`. + +### Occurrence is zero + +If the [Occurrence][Occurrence Property] is set to `0`, the variable specified in the [Index][Index Property] property is set to `-1`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} +[Index Property]: {{< ref "#index" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-indexes-of-items-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-indexes-of-items-with-value-block-2.md new file mode 100644 index 000000000..db2ee6f45 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/Get-Index/get-indexes-of-items-with-value-block-2.md @@ -0,0 +1,153 @@ +--- +title: "Get Indexes Of Items With Value" +linkTitle: "Get Indexes Of Items With Value" +description: "Gets the indexes of all items in a List matching a value." +--- + +{{< figure src="/blocks/lists-get-index-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetIndex.GetIndexesOfItemsWithValueBlock`2)
+ +## Description + +Gets the [Indexes][Indexes Property] of all items in a [List][List Property] matching a [Value][Value Property]. + +## Examples + +### Get the Indexes of all items in a List matching a Value + +This example will attempt to get the indexes of all items matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +Attempting to get the indexes of all items matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)Indexes` being updated to the following: + +```json +[0, 5] +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Indexes][Indexes Property] of matching items from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the items to get the [Indexes][Indexes Property] of must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Indexes + +[IList][]<[Int32][]> containing the [Indexes][Indexes Property] of items matching [Value][Value Property] in [List][List Property]. + +If there are no items matching [Value][Value Property] in [List][List Property], the specified variable will be set to `[-1]`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[Int32][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Indexes` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Indexes][Indexes Property] property is set to `[-1]`. + +### No items matching Value + +If [List][List Property] does not contain items matching the specified [Value][Value Property], the variable specified in the [Indexes][Indexes Property] property is set to `[-1]`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[Indexes Property]: {{< ref "#indexes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/_index.md new file mode 100644 index 000000000..81c3fb421 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/_index.md @@ -0,0 +1,5 @@ +--- +title: "Lists" +linkTitle: "Lists" +description: "Blocks related to working with Lists." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/_index.md new file mode 100644 index 000000000..46346dea3 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Add Item(s)" +linkTitle: "Add Item(s)" +description: "Add an item or multiple items to a list." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-beginning-block-2.md new file mode 100644 index 000000000..c8b95f5da --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-beginning-block-2.md @@ -0,0 +1,137 @@ +--- +title: "Add Item At Beginning" +linkTitle: "Add Item At Beginning" +description: "Adds an Item at the beginning of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemAtBeginningBlock`2)
+ +## Description + +Adds an [Item][Item Property] at the beginning of a [List][List Property]. + +## Examples + +### Add an Item at the beginning of an empty List + +This example will add `"New Item"` at the beginning of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | + +#### Result + +Adding `"New Item"` at the beginning of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item"] +``` + +*** + +### Add an Item at the beginning of a List + +This example will add `"New Item"` at the beginning of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | + +#### Result + +Adding `"New Item"` at the beginning of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["New Item", "Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Item][Item Property] is added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Item + +The [Item][Item Property] to be added at the beginning of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Item][Item Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-end-block-2.md new file mode 100644 index 000000000..6343dc1f4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-end-block-2.md @@ -0,0 +1,138 @@ +--- +title: "Add Item At End" +linkTitle: "Add Item At End" +description: "Adds an Item at the end of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemAtEndBlock`2)
+ +## Description + +Adds an [Item][Item Property] at the end of a [List][List Property]. + +## Examples + +### Add an Item at the end of an empty List + +This example will add `"New Item"` at the end of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | + +#### Result + +Adding `"New Item"` at the end of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item"] +``` + +*** + +### Add an Item at the end of a List + +This example will add `"New Item"` at the end of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | + +#### Result + +Adding `"New Item"` at the end of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1, "New Item"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Item][Item Property] is added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Item + +The [Item][Item Property] to be added at the end of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Item][Item Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-index-block-2.md new file mode 100644 index 000000000..bd220f095 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-item-at-index-block-2.md @@ -0,0 +1,186 @@ +--- +title: "Add Item At Index" +linkTitle: "Add Item At Index" +description: "Adds an Item at the specified Index of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemAtIndexBlock`2)
+ +## Description + +Adds an [Item][Item Property] at the specified [Index][Index Property] of a [List][List Property]. + +## Examples + +### Add an Item at the first Index (i.e. `0`) of an empty List + +This example will add `"New Item"` at index `0` of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `"New Item"` at index `0` of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item"] +``` + +*** + +### Add an Item at the first Index (i.e. `0`) of a List + +This example will add `"New Item"` at index `0` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `"New Item"` at index `0` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["New Item", "Some Text", 1] +``` + +*** + +### Add an Item at the end (i.e. Index equals count of items) of a List + +This example will add `"New Item"` at index `2` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with value `"New Item"` | `($)Item` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `2` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `"New Item"` at index `2` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1, "New Item"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Item][Item Property] is added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Item + +The [Item][Item Property] to be added at the specified [Index][Index Property] of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Index + +The [Index][Index Property] to add the [Item][Item Property] at. + +Valid values are between and including `0` and the total count of items in the [List][List Property]. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Item][Item Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is out of the range of the list indexes. Valid indexes are between and including `0` and the count of items in the [List][List Property]. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Item Property]: {{< ref "#item" >}} +[Index Property]: {{< ref "#index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-beginning-block-2.md new file mode 100644 index 000000000..c3217127d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-beginning-block-2.md @@ -0,0 +1,139 @@ +--- +title: "Add Items At Beginning" +linkTitle: "Add Items At Beginning" +description: "Adds Items at the beginning of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemsAtBeginningBlock`2)
+ +## Description + +Adds [Items][Items Property] at the beginning of a [List][List Property]. + +## Examples + +### Add Items at the beginning of an empty List + +This example will add `["New Item 1", "New Item 2"]` at the beginning of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at the beginning of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item 1", "New Item 2"] +``` + +*** + +### Add Items at the beginning of a List + +This example will add `["New Item 1", "New Item 2"]` at the beginning of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at the beginning of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["New Item 1", "New Item 2", "Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Items][Items Property] are added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Items + +The [Items][Items Property] to be added at the beginning of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Items][Items Property] is `null`. | + +## Remarks + +### Empty Items + +If [Items][Items Property] is empty (i.e. `[]`) there is nothing to add, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-end-block-2.md new file mode 100644 index 000000000..47cdbcb01 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-end-block-2.md @@ -0,0 +1,139 @@ +--- +title: "Add Items At End" +linkTitle: "Add Items At End" +description: "Adds Items at the end of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemsAtEndBlock`2)
+ +## Description + +Adds [Items][Items Property] at the end of a [List][List Property]. + +## Examples + +### Add Items at the end of an empty List + +This example will add `["New Item 1", "New Item 2"]` at the end of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at the end of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item 1", "New Item 2"] +``` + +*** + +### Add Items at the end of a List + +This example will add `["New Item 1", "New Item 2"]` at the end of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at the end of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1, "New Item 1", "New Item 2"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Items][Items Property] are added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Items + +The [Items][Items Property] to be added at the end of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Items][Items Property] is `null`. | + +## Remarks + +### Empty Items + +If [Items][Items Property] is empty (i.e. `[]`) there is nothing to add, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-index-block-2.md new file mode 100644 index 000000000..85614e718 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/add-item/add-items-at-index-block-2.md @@ -0,0 +1,185 @@ +--- +title: "Add Items At Index" +linkTitle: "Add Items At Index" +description: "Adds Items at the specified Index of a List." +--- + +{{< figure src="/blocks/lists-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.AddItem.AddItemsAtIndexBlock`2)
+ +## Description + +Adds [Items][Items Property] at the specified [Index][Index Property] of a [List][List Property]. + +## Examples + +### Add Items at the first index (i.e. `0`) of an empty List + +This example will add `["New Item 1", "New Item 2"]` at index `0` of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at index `0` of `[]` results in the variable `($)List` being updated to the following: + +```json +["New Item 1", "New Item 2"] +``` + +*** + +### Add Items at the first Index (i.e. `0`) of a List + +This example will add `["New Item 1", "New Item 2"]` at index `0` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at index `0` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["New Item 1", "New Item 2", "Some Text", 1] +``` + +*** + +### Add Items at the end (i.e. Index equals count of items) of a List + +This example will add `["New Item 1", "New Item 2"]` at index `2` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Items][Items Property] | `($)Items`, with value `["New Item 1", "New Item 2"]` | `($)Items` is a variable of type [IEnumerable][]<[String][]> | +| [Index][Index Property] | `($)Index`, with value `2` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `["New Item 1", "New Item 2"]` at index `2` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1, "New Item 1", "New Item 2"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the [Items][Items Property] are added. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be added to the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Items + +The [Items][Items Property] to be added at the specified [Index][Index Property] of the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Index + +The [Index][Index Property] to add the [Items][Items Property] at. + +Valid values are between and including `0` and the total count of items in the [List][List Property]. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Items][Items Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is out of the range of the list indexes. Valid indexes are between and including `0` and the count of items in the [List][List Property]. | + +## Remarks + +### Empty Items + +If [Items][Items Property] is empty (i.e. `[]`) there is nothing to add, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Items Property]: {{< ref "#items" >}} +[Index Property]: {{< ref "#index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/_index.md new file mode 100644 index 000000000..30f4fc7df --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Contains Item(s)" +linkTitle: "Contains Item(s)" +description: "Check if an item or multiple items are contained in a list." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-item-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-item-with-value-block-2.md new file mode 100644 index 000000000..9f91f15b2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-item-with-value-block-2.md @@ -0,0 +1,167 @@ +--- +title: "Contains Item With Value" +linkTitle: "Contains Item With Value" +description: "Checks if a List contains at least one item matching the specified value." +--- + +{{< figure src="/blocks/lists-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.ContainsItem.ContainsItemWithValueBlock`2)
+ +## Description + +Checks if [List][List Property] contains at least one item matching [Value][Value Property]. + +## Examples + +### List contains item with Value + +This example will check whether `[1, 2, 3, 3, 2, 1]` contains the value `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`[1, 2, 3, 3, 2, 1]` contains two items with the value `1`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +true +``` + +*** + +### List does not contain item with Value + +This example will check whether `[1, 2, 3, 3, 2, 1]` contains the value `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `10` | `($)Value` is a variable of type [Int32][] | +| [Contains Item][ContainsItem Property] | `($)ContainsItem`, with no value | `($)ContainsItem` is a variable that will be set to a [Boolean][] value | + +#### Result + +`[1, 2, 3, 3, 2, 1]` does not contain any items with the value `10`. Therefore, the variable `($)ContainsItem` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### List + +The [List][List Property] to check whether it contains at least one item matching the specified [Value][Value Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] to check for matching items. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Item + +The result of the contains item check. + +If [List][List Property] contains at least one item matching the specified [Value][Value Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItem` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Contains Item][ContainsItem Property] property is set to `false`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[ContainsItem Property]: {{< ref "#contains-item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-items-with-values-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-items-with-values-block-2.md new file mode 100644 index 000000000..a8ca644ee --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/contains-item/contains-items-with-values-block-2.md @@ -0,0 +1,168 @@ +--- +title: "Contains Items With Values" +linkTitle: "Contains Items With Values" +description: "Checks if a List contains at least one item matching each of the specified values." +--- + +{{< figure src="/blocks/lists-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.ContainsItem.ContainsItemsWithValuesBlock`2)
+ +## Description + +Checks if [List][List Property] contains at least one item matching each of the specified [Values][Values Property]. + +## Examples + +### List contains items with Values + +This example will check whether `[1, 2, 3, 3, 2, 1]` contains at least one item matching each of the values in `[1, 2, 3]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`[1, 2, 3, 3, 2, 1]` contains at least one item matching each of the values in `[1, 2, 3]`; it contains two items with the value `1`, two items with the value `2` and two items with the value `3`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +true +``` + +*** + +### List does not contain items with Values + +This example will check whether `[1, 2, 3, 3, 2, 1]` contains at least one item matching each of the values in `[1, 2, 3, 10]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3, 10]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Contains Items][ContainsItems Property] | `($)ContainsItems`, with no value | `($)ContainsItems` is a variable that will be set to a [Boolean][] value | + +#### Result + +`[1, 2, 3, 3, 2, 1]` does not contain at least one item matching each of the values in `[1, 2, 3, 10]`; it contains two items with the value `1`, two items with the value `2` and two items with the value `3`, but no items with the value `10`. Therefore, the variable `($)ContainsItems` will be updated to the following: + +```json +false +``` + +*** + +## Properties + +### List + +The [List][List Property] to check whether it contains at least one item matching each of the specified [Values][Values Property]. + +Items are considered matching if they have a value matching one of the specified [Values][Values Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Values + +The [Values][Values Property] to check for matching items. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Contains Items + +The result of the contains items check. + +If [List][List Property] contains at least one item matching each of the specified [Values][Values Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsItems` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] or [Values][Values Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`), the variable specified in the [Contains Items][ContainsItems Property] property is set to `false`. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Values Property]: {{< ref "#values" >}} +[ContainsItems Property]: {{< ref "#contains-items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/_index.md new file mode 100644 index 000000000..cb3bb09ff --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Item(s)" +linkTitle: "Get Item(s)" +description: "Get an item or multiple items from a list." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-beginning-block-2.md new file mode 100644 index 000000000..b107fc830 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-beginning-block-2.md @@ -0,0 +1,113 @@ +--- +title: "Get Item At Beginning" +linkTitle: "Get Item At Beginning" +description: "Gets the item at the beginning of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemAtBeginningBlock`2)
+ +## Description + +Gets the [Item][Item Property] at the beginning of a [List][List Property]. + +## Examples + +### Get the Item at the beginning of a List + +This example will get the item at the beginning of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [String]) | + +#### Result + +Getting the item at the beginning of `["Some Text", 1]` results in the variable `($)Item` being updated to the following: + +```json +"Some Text" +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the item from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Item + +The [Item][Item Property] at the beginning of [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-end-block-2.md new file mode 100644 index 000000000..72c195e61 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-end-block-2.md @@ -0,0 +1,113 @@ +--- +title: "Get Item At End" +linkTitle: "Get Item At End" +description: "Gets the item at the end of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemAtEndBlock`2)
+ +## Description + +Gets the [Item][Item Property] at the end of a [List][List Property]. + +## Examples + +### Get the Item at the end of a List + +This example will get the item at the end of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [Int32]) | + +#### Result + +Getting the item at the end of `["Some Text", 1]` results in the variable `($)Item` being updated to the following: + +```json +1 +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the item from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Item + +The [Item][Item Property] at the end of [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-index-block-2.md new file mode 100644 index 000000000..4a9000a42 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-item-at-index-block-2.md @@ -0,0 +1,157 @@ +--- +title: "Get Item At Index" +linkTitle: "Get Item At Index" +description: "Gets the item at the specified index of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemAtIndexBlock`2)
+ +## Description + +Gets the [Item][Item Property] at the specified [Index][Index Property] of a [List][List Property]. + +## Examples + +### Get the Item at the first Index (i.e. `0`) of a List + +This example will get the item at index `0` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [String]) | + +#### Result + +Getting the item at index `0` of `["Some Text", 1]` results in the variable `($)Item` being updated to the following: + +```json +"Some Text" +``` + +*** + +### Get the Item at the last Index (i.e. Index equals count of items - `1`) of a List + +This example will get the item at index `1` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `1` | `($)Index` is a variable of type [Int32][] | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [Int32]) | + +#### Result + +Getting the item at index `1` of `["Some Text", 1]` results in the variable `($)Item` being updated to the following: + +```json +1 +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the item from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Index + +The [Index][Index Property] to get the item at. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Item + +The [Item][Item Property] at the specified [Index][Index Property] of [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Item` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [List][List Property] contains no items. | +| | Thrown when [Index][Index Property] is out of the range of the list indexes. Valid indexes are between and including `0` and the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Index Property]: {{< ref "#index" >}} +[Item Property]: {{< ref "#item" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-beginning-block-2.md new file mode 100644 index 000000000..2e3dc1817 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-beginning-block-2.md @@ -0,0 +1,137 @@ +--- +title: "Get Items At Beginning" +linkTitle: "Get Items At Beginning" +description: "Gets a count of items at the beginning of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemsAtBeginningBlock`2)
+ +## Description + +Gets the specified [Count][Count Property] of [Items][Items Property] at the beginning of a [List][List Property]. + +## Examples + +### Get Count of Items at the beginning of a List + +This example will get `2` items at the beginning of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[dynamic][]> value | + +#### Result + +Getting `2` items from the beginning of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)Items` being updated to the following: + +```json +["Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Items][Items Property] from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Count + +The [Count][Count Property] of [Items][Items Property] to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Items + +The [Items][Items Property] at the beginning of [List][List Property]. + +[Items][Items Property] will be in the same order they are defined in [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Negative Count + +If [Count][Count Property] is negative, [Items][Items Property] contains all items in the [List][List Property]. + +### Zero Count + +If [Count][Count Property] is `0`, [Items][Items Property] is set to an empty list (i.e. `[]`). + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Count Property]: {{< ref "#count" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-end-block-2.md new file mode 100644 index 000000000..3bbe88f0c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-end-block-2.md @@ -0,0 +1,137 @@ +--- +title: "Get Items At End" +linkTitle: "Get Items At End" +description: "Gets a count of items at the end of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemsAtEndBlock`2)
+ +## Description + +Gets the specified [Count][Count Property] of [Items][Items Property] at the end of a [List][List Property]. + +## Examples + +### Get Count of Items at the end of a List + +This example will get `2` items at the end of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[dynamic][]> value | + +#### Result + +Getting `2` items from the end of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)Items` being updated to the following: + +```json +["Some More Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Items][Items Property] from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Count + +The [Count][Count Property] of [Items][Items Property] to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Items + +The [Items][Items Property] at the end of [List][List Property]. + +[Items][Items Property] will be in the same order they are defined in [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Negative Count + +If [Count][Count Property] is negative, [Items][Items Property] contains all items in the [List][List Property]. + +### Zero Count + +If [Count][Count Property] is `0`, [Items][Items Property] is set to an empty list (i.e. `[]`). + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Count Property]: {{< ref "#count" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-index-block-2.md new file mode 100644 index 000000000..ca52461af --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-index-block-2.md @@ -0,0 +1,162 @@ +--- +title: "Get Items At Index" +linkTitle: "Get Items At Index" +description: "Gets a count of items starting at the specified index of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemsAtIndexBlock`2)
+ +## Description + +Gets the specified [Count][Count Property] of [Items][Items Property] starting at the given [Index][Index Property] of a [List][List Property]. + +## Examples + +### Get Count of Items at the first Index (i.e. `0`) of a List + +This example will get `2` items at index `0` of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[dynamic][]> value | + +#### Result + +Getting `2` items at index `0` of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)Items` being updated to the following: + +```json +["Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Items][Items Property] from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Index + +The [Index][Index Property] to get the [Count][Count Property] of [Items][Items Property] at. This is an inclusive index, which means the item at the specified index will be included. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Count + +The [Count][Count Property] of [Items][Items Property] to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Items + +The [Items][Items Property] at the specified [Index][Index Property] of [List][List Property]. + +[Items][Items Property] will be in the same order they are defined in [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is less than `0` or greater than the count of items in [List][List Property] - `1`. | +| | Thrown when [Index][Index Property] + [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Index is inclusive + +The [Index][Index Property] is an inclusive [index][Indexes], which means the item at the index will be included in [Items][Items Property]. + +### Negative Count + +If [Count][Count Property] is negative, [Items][Items Property] contains all items after and including the item at the specified [Index][Index Property] in the [List][List Property]. + +### Zero Count + +If [Count][Count Property] is `0`, [Items][Items Property] is set to an empty list (i.e. `[]`). + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Index Property]: {{< ref "#index" >}} +[Count Property]: {{< ref "#count" >}} +[Items Property]: {{< ref "#items" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-indexes-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-indexes-block-2.md new file mode 100644 index 000000000..50d62f8a4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/get-item/get-items-at-indexes-block-2.md @@ -0,0 +1,139 @@ +--- +title: "Get Items At Indexes" +linkTitle: "Get Items At Indexes" +description: "Gets the items at each of the specified indexes of a List." +--- + +{{< figure src="/blocks/lists-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.GetItem.GetItemsAtIndexesBlock`2)
+ +## Description + +Gets the [Items][Items Property] at each of the specified [Indexes][Indexes Property] of a [List][List Property]. + +## Examples + +### Get Items at the first and third Indexes (i.e. [`0`, `2`]) of a List + +This example will get items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Indexes][Indexes Property] | `($)Indexes`, with value [`0`, `2`] | `($)Indexes` is a variable of type [IEnumerable][]<[Int32][]> | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to an [IList][]<[dynamic][]> value | + +#### Result + +Getting items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)Items` being updated to the following: + +```json +["Some Text", "Some More Text"] +``` + +*** + +## Properties + +### List + +The [List][List Property] to get the [Items][Items Property] from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Indexes + +The [Indexes][Indexes Property] of the [Items][Items Property] to get. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[Int32][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Lists.RemoveItem.RemoveAllItemsBlock`2)
+ +## Description + +Removes all items from a [List][List Property]. + +## Examples + +### Remove all items from an empty List + +This example will attempt to remove all items from `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Attempting to remove all items from `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove all items from a List + +This example will remove all items from `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Removing all items from `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +[] +``` + +*** + +## Properties + +### List + +The [List][List Property] where all items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-duplicate-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-duplicate-items-block-2.md new file mode 100644 index 000000000..d0b3803bc --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-duplicate-items-block-2.md @@ -0,0 +1,153 @@ +--- +title: "Remove Duplicate Items" +linkTitle: "Remove Duplicate Items" +description: "Removes duplicate items from a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveDuplicateItemsBlock`2)
+ +## Description + +Removes duplicate items from a [List][List Property]. + +## Examples + +### Remove duplicate items from an empty List + +This example will attempt to remove duplicate items from `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Attempting to remove duplicate items from `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove duplicate items from a List without duplicates + +This example will attempt to remove duplicate items from `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Attempting to remove duplicate items from `["Some Text", 1]` results in no operation, as there are no duplicates to remove. Therefore, the variable `($)List` remains: + +```json +["Some Text", 1] +``` + +*** + +### Remove duplicate items from a List containing duplicates + +This example will remove duplicate items from `["Some Text", 1, "Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Removing duplicate items from `["Some Text", 1, "Some Text", 1]` results in the second occurrences of `"Some Text"` and `1` being removed; with the variable `($)List` being updated to the following: + +```json +["Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] where duplicate items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +For information and examples of how it is determined whether two items are considered the same, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### List with no duplicates + +If [List][List Property] does not contain duplicates there is nothing to remove, so no operation is performed. + +### Which duplicates are removed? + +If [List][List Property] contains duplicates, the first occurrences of the duplicated items are kept; all other occurrences are removed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-beginning-block-2.md new file mode 100644 index 000000000..88032c710 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-beginning-block-2.md @@ -0,0 +1,121 @@ +--- +title: "Remove Item At Beginning" +linkTitle: "Remove Item At Beginning" +description: "Removes the item at the beginning of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtBeginningBlock`2)
+ +## Description + +Removes the item at the beginning of a [List][List Property]. + +## Examples + +### Remove the Item at the beginning of an empty List + +This example will attempt to remove the item at the beginning of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Attempting to remove the item at the beginning of `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove the Item at the beginning of a List + +This example will remove the item at the beginning of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Removing the item at the beginning of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +[1] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the item is removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-end-block-2.md new file mode 100644 index 000000000..a128b122d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-end-block-2.md @@ -0,0 +1,121 @@ +--- +title: "Remove Item At End" +linkTitle: "Remove Item At End" +description: "Removes the item at the end of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtEndBlock`2)
+ +## Description + +Removes the item at the end of a [List][List Property]. + +## Examples + +### Remove the Item at the end of an empty List + +This example will attempt to remove the item at the end of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Attempting to remove the item at the end of `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove the Item at the end of a List + +This example will remove the item at the end of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | + +#### Result + +Removing the item at the end of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the item is removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-index-block-2.md new file mode 100644 index 000000000..20c7208c9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-at-index-block-2.md @@ -0,0 +1,163 @@ +--- +title: "Remove Item At Index" +linkTitle: "Remove Item At Index" +description: "Removes the item at the specified index of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtIndexBlock`2)
+ +## Description + +Removes the item at the specified [Index][Index Property] of a [List][List Property]. + +## Examples + +### Remove the Item at the first Index (i.e. `0`) of an empty List + +This example will attempt to remove the item at index `0` of `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Attempting to remove the item at index `0` of `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove the Item at the first Index (i.e. `0`) of a List + +This example will remove the item at index `0` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Removing the item at index `0` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +[1] +``` + +*** + +### Remove the Item at the last Index (i.e. Index equals count of items - `1`) of a List + +This example will remove the item at index `1` of `["Some Text", 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `1` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Remove the item at index `1` of `["Some Text", 1]` results in the variable `($)List` being updated to the following: + +```json +["Some Text"] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the item is removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Index + +The [Index][Index Property] to remove the item at. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is out of the range of the list indexes. Valid indexes are between and including `0` and the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Index Property]: {{< ref "#index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-with-value-block-2.md new file mode 100644 index 000000000..52864c8bc --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-item-with-value-block-2.md @@ -0,0 +1,207 @@ +--- +title: "Remove Item With Value" +linkTitle: "Remove Item With Value" +description: "Removes the specified occurrence of an item matching a value from a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemWithValueBlock`2)
+ +## Description + +Removes the specified [Occurrence][Occurrence Property] of an item matching a [Value][Value Property] from a [List][List Property]. + +## Examples + +### Remove the first Occurrence of an item matching a Value from an empty List + +This example will attempt to remove the first occurrence of an item matching the value `1` from `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +Attempting to remove the first occurrence of an item matching the value `1` from `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove the first Occurrence of an item matching a Value from a List + +This example will attempt to remove the first occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means remove the first occurrence; `2` means second etc. + +Attempting to remove the first occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)List` being updated to the following: + +```json +[2, 3, 3, 2, 1] +``` + +*** + +### Remove the last Occurrence of an item matching a Value from a List + +This example will attempt to remove the last occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means remove the last occurrence; `-2` means second last etc. + +Attempting to remove the last occurrence of an item matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)List` being updated to the following: + +```json +[1, 2, 3, 3, 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to remove the specified [Occurrence][Occurrence Property] of matching item from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the item to remove must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to remove from the [List][List Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Occurrences + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### No items matching Value, or Occurrence is not present + +If [List][List Property] does not contain items matching the specified [Value][Value Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-beginning-block-2.md new file mode 100644 index 000000000..fd75051bd --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-beginning-block-2.md @@ -0,0 +1,123 @@ +--- +title: "Remove Items At Beginning" +linkTitle: "Remove Items At Beginning" +description: "Removes a count of items from the beginning of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtBeginningBlock`2)
+ +## Description + +Removes the specified [Count][Count Property] of items from the beginning of a [List][List Property]. + +## Examples + +### Remove Count of items from the beginning of a List + +This example will remove `2` items from the beginning of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | + +#### Result + +Removing `2` items from the beginning of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)List` being updated to the following: + +```json +["Some More Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Count + +The [Count][Count Property] of items to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Negative Count + +If [Count][Count Property] is negative all items in the [List][List Property] are removed. + +### Zero Count + +If [Count][Count Property] is `0` there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Count Property]: {{< ref "#count" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-end-block-2.md new file mode 100644 index 000000000..7a1deefb6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-end-block-2.md @@ -0,0 +1,123 @@ +--- +title: "Remove Items At End" +linkTitle: "Remove Items At End" +description: "Removes a count of items from the end of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtEndBlock`2)
+ +## Description + +Removes the specified [Count][Count Property] of items from the end of a [List][List Property]. + +## Examples + +### Remove Count of items from the end of a List + +This example will remove `2` items from the end of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | + +#### Result + +Removing `2` items from the end of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Count + +The [Count][Count Property] of items to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Negative Count + +If [Count][Count Property] is negative all items in the [List][List Property] are removed. + +### Zero Count + +If [Count][Count Property] is `0` there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Count Property]: {{< ref "#count" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-index-block-2.md new file mode 100644 index 000000000..688e116b8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-index-block-2.md @@ -0,0 +1,148 @@ +--- +title: "Remove Items At Index" +linkTitle: "Remove Items At Index" +description: "Removes a count of items starting at the specified index of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtIndexBlock`2)
+ +## Description + +Removes the specified [Count][Count Property] of items starting at the given [Index][Index Property] of a [List][List Property]. + +## Examples + +### Remove Count of items at the first Index (i.e. `0`) of a List + +This example will remove `2` items at index `0` of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | + +#### Result + +Removing `2` items at index `0` of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)List` being updated to the following: + +```json +["Some More Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Index + +The [Index][Index Property] to remove the [Count][Count Property] of items at. This is an inclusive index, which means the item at the specified index will be included. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Count + +The [Count][Count Property] of items to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is less than `0` or greater than the count of items in [List][List Property] - `1`. | +| | Thrown when [Index][Index Property] + [Count][Count Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Index is inclusive + +The [Index][Index Property] is an inclusive [index][Indexes], which means the item at the index will be included in the removed items. + +### Negative Count + +If [Count][Count Property] is negative all items after and including the specified [Index][Index property] in the [List][List Property] are removed. + +### Zero Count + +If [Count][Count Property] is `0` there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Index Property]: {{< ref "#index" >}} +[Count Property]: {{< ref "#count" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-indexes-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-indexes-block-2.md new file mode 100644 index 000000000..1315b48f6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-at-indexes-block-2.md @@ -0,0 +1,125 @@ +--- +title: "Remove Items At Indexes" +linkTitle: "Remove Items At Indexes" +description: "Removes the items at each of the specified indexes of a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtIndexesBlock`2)
+ +## Description + +Removes the items at each of the specified [Indexes][Indexes Property] of a [List][List Property]. + +## Examples + +### Remove items at the first and third Indexes (i.e. [`0`, `2`]) of a List + +This example will remove items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Indexes][Indexes Property] | `($)Indexes`, with value [`0`, `2`] | `($)Indexes` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Removing items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]` results in the variable `($)List` being updated to the following: + +```json +[1, 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] where the items are removed from. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Indexes + +The [Indexes][Indexes Property] of the items to remove. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[Int32][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Lists.RemoveItem.RemoveItemsWithValueBlock`2)
+ +## Description + +Removes all items matching a [Value][Value Property] from a [List][List Property]. + +## Examples + +### Remove all items matching a Value from an empty List + +This example will attempt to remove all items matching the value `1` from `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | + +#### Result + +Attempting to remove all items matching the value `1` from `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove all items matching a Value from a List + +This example will attempt to remove all items matching the value `1` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | + +#### Result + +Attempting to remove all items matching the value `1` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)List` being updated to the following: + +```json +[2, 3, 3, 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to remove all matching items from. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the items to remove must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### No items matching Value + +If [List][List Property] does not contain items matching the specified [Value][Value Property], there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-with-values-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-with-values-block-2.md new file mode 100644 index 000000000..87f4429b0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/remove-item/remove-items-with-values-block-2.md @@ -0,0 +1,161 @@ +--- +title: "Remove Items With Values" +linkTitle: "Remove Items With Values" +description: "Removes all items matching one of the specified values from a List." +--- + +{{< figure src="/blocks/lists-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.RemoveItem.RemoveItemsWithValuesBlock`2)
+ +## Description + +Removes all items matching one of the specified [Values][Values Property] from a [List][List Property]. + +## Examples + +### Remove all items matching one of the specified Values from an empty List + +This example will attempt to remove all items matching one of the values `[1, 2]` from `[]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to remove all items matching one of the values `[1, 2]` from `[]` results in no operation, as there is nothing to remove. Therefore, the variable `($)List` remains: + +```json +[] +``` + +*** + +### Remove all items matching one of the specified Values from a List + +This example will attempt to remove all items matching one of the values `[1, 2]` from `[1, 2, 3, 3, 2, 1]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to remove all items matching one of the values `[1, 2]` from `[1, 2, 3, 3, 2, 1]` results in the variable `($)List` being updated to the following: + +```json +[3, 3] +``` + +*** + +## Properties + +### List + +The [List][List Property] to remove all matching items from. + +Items are considered matching if they have one of the specified [Values][Values Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items that can be removed from the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Values + +The [Values][Values Property] the items to remove must match one of. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Values][Values Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to remove, so no operation is performed. + +### Empty Values + +If [Values][Values Property] is empty (i.e. `[]`) there are no values to match, therefore nothing can be removed and no operation is performed. + +### No items matching a specified value in Values + +If [List][List Property] does not contain items matching one of the specified [Values][Values Property], there is nothing to remove for that value. + +### No items matching Values + +If [List][List Property] does not contain items matching any of the specified [Values][Values Property], there is nothing to remove, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Values Property]: {{< ref "#values" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/_index.md new file mode 100644 index 000000000..1a848c4be --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Set Item(s)" +linkTitle: "Set Item(s)" +description: "Set an item or multiple items in a list to a new value." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-all-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-all-items-block-2.md new file mode 100644 index 000000000..e4439826e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-all-items-block-2.md @@ -0,0 +1,122 @@ +--- +title: "Set All Items" +linkTitle: "Set All Items" +description: "Sets all items in a List to a new value." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetAllItemsBlock`2)
+ +## Description + +Sets all items in a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set all items in a List to a New Value + +This example will set all items in `["Some Text", 1]` to `"New Value"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `"New Value"` | `($)NewValue` is a variable of type [String] | + +#### Result + +Setting all items in `["Some Text", 1]` to `"New Value"` results in the variable `($)List` being updated to the following: + +```json +["New Value", "New Value"] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set all items in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Value + +The [New Value][NewValue Property] to set all items in [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-beginning-block-2.md new file mode 100644 index 000000000..3e7487761 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-beginning-block-2.md @@ -0,0 +1,120 @@ +--- +title: "Set Item At Beginning" +linkTitle: "Set Item At Beginning" +description: "Sets the item at the beginning of a List to a new value." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemAtBeginningBlock`2)
+ +## Description + +Sets the item at the beginning of a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the item at the beginning of a List to a New Value + +This example will set the item at the beginning of `["Some Text", 1]` to `"Some Modified Text"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `"Some Modified Text"` | `($)NewValue` is a variable of type [String] | + +#### Result + +Setting the item at the beginning of `["Some Text", 1]` to `"Some Modified Text"` results in the variable `($)List` being updated to the following: + +```json +["Some Modified Text", 1] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the item in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Value + +The [New Value][NewValue Property] to set the item at the beginning of [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-end-block-2.md new file mode 100644 index 000000000..c63fbffc6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-end-block-2.md @@ -0,0 +1,120 @@ +--- +title: "Set Item At End" +linkTitle: "Set Item At End" +description: "Sets the item at the end of a List to a new value." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemAtEndBlock`2)
+ +## Description + +Sets the item at the end of a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the item at the end of a List to a New Value + +This example will set the item at the end of `["Some Text", 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32] | + +#### Result + +Setting the item at the end of `["Some Text", 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the item in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Value + +The [New Value][NewValue Property] to set the item at the end of [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-index-block-2.md new file mode 100644 index 000000000..6be27b142 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-at-index-block-2.md @@ -0,0 +1,163 @@ +--- +title: "Set Item At Index" +linkTitle: "Set Item At Index" +description: "Sets the item at the specified index of a List to a new value." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemAtIndexBlock`2)
+ +## Description + +Sets the item at the specified [Index][Index Property] of a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the Item at the first Index (i.e. `0`) of a List to a New Value + +This example will set the item at index `0` of `["Some Text", 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Setting the item at index `0` of `["Some Text", 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +[10, 1] +``` + +*** + +### Set the Item at the last Index (i.e. Index equals count of items - `1`) of a List + +This example will set the item at index `1` of `["Some Text", 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32] | +| [Index][Index Property] | `($)Index`, with value `1` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Setting the item at index `1` of `["Some Text", 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +["Some Text", 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the item in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Value + +The [New Value][NewValue Property] to set the item at the specified [Index][Index Property] of [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Index + +The [Index][Index Property] to set the item at. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [New Value][NewValue Property] is `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [List][List Property] contains no items. | +| | Thrown when [Index][Index Property] is out of the range of the list indexes. Valid indexes are between and including `0` and the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValue Property]: {{< ref "#new-value" >}} +[Index Property]: {{< ref "#index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-with-value-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-with-value-block-2.md new file mode 100644 index 000000000..54437ace7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-item-with-value-block-2.md @@ -0,0 +1,200 @@ +--- +title: "Set Item With Value" +linkTitle: "Set Item With Value" +description: "Sets the specified occurrence of an item matching a value in a List to a new value." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemWithValueBlock`2)
+ +## Description + +Sets the specified [Occurrence][Occurrence Property] of an item matching a [Value][Value Property] in a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set the first Occurrence of an item matching a Value in a List to a New Value + +This example will attempt to set the first occurrence of an item matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means set the first occurrence; `2` means second etc. + +Attempting to set the first occurrence of an item matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +[10, 2, 3, 3, 2, 1] +``` + +*** + +### Set the last Occurrence of an item matching a Value in a List to a New Value + +This example will attempt to set the last occurrence of an item matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means set the last occurrence; `-2` means second last etc. + +Attempting to set the last occurrence of an item matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +[1, 2, 3, 3, 2, 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the specified [Occurrence][Occurrence Property] of matching item in. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the item to set must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set the specified [Occurrence][Occurrence Property] of matching item in [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Occurrence + +The [Occurrence][Occurrence Property] of matching item to set in the [List][List Property]. + +Items are considered matching if they have the specified [Value][Value Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] or [New Value][NewValue Property] are `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Occurrences + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### No items matching Value, or Occurrence is not present + +If [List][List Property] does not contain items matching the specified [Value][Value Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[NewValue Property]: {{< ref "#new-value" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-beginning-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-beginning-block-2.md new file mode 100644 index 000000000..650f6fcca --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-beginning-block-2.md @@ -0,0 +1,123 @@ +--- +title: "Set Items At Beginning" +linkTitle: "Set Items At Beginning" +description: "Sets the items at the beginning of a List to new values." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemsAtBeginningBlock`2)
+ +## Description + +Sets the items at the beginning of a [List][List Property] to [New Values][NewValues Property]. + +## Examples + +### Set the items at the beginning of a List to New Values + +This example will set the first and second items at the beginning of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Values][NewValues Property] | `($)NewValues`, with value `["Some Modified Text", 10]` | `($)NewValues` is a variable of type [IEnumerable][]<[dynamic][]> | + +#### Result + +Setting the first and second items at the beginning of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively, results in the variable `($)List` being updated to the following: + +```json +["Some Modified Text", 10, "Some More Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the items in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Values + +The [New Values][NewValues Property] to set the items at the beginning of [List][List Property] to. + +The number of items in [New Values][NewValues Property] determines the number of items that will be set at the beginning of [List][List Property]. One item means only the first item is set, two items means the first and second items are set etc. + +The first item in [List][List Property] will be set to the first value in [New Values][NewValues Property]; the second item in [List][List Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] or [New Values][NewValues Property] is `null`. | + +## Remarks + +### Empty New Values + +If [New Values][NewValues Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValues Property]: {{< ref "#new-values" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-end-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-end-block-2.md new file mode 100644 index 000000000..833702012 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-end-block-2.md @@ -0,0 +1,123 @@ +--- +title: "Set Items At End" +linkTitle: "Set Items At End" +description: "Sets the items at the end of a List to new values." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemsAtEndBlock`2)
+ +## Description + +Sets the items at the end of a [List][List Property] to [New Values][NewValues Property]. + +## Examples + +### Set the items at the end of a List to New Values + +This example will set the second last and last items at the end of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Values][NewValues Property] | `($)NewValues`, with value `["Some Modified Text", 10]` | `($)NewValues` is a variable of type [IEnumerable][]<[dynamic][]> | + +#### Result + +Setting the second last and last items at the end of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively, results in the variable `($)List` being updated to the following: + +```json +["Some Text", 1, "Some Modified Text", 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the items in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Values + +The [New Values][NewValues Property] to set the items at the end of [List][List Property] to. + +The number of items in [New Values][NewValues Property] determines the number of items that will be set at the end of [List][List Property]. One item means only the last item is set, two items means the second last and last items are set etc. + +The last item in [List][List Property] will be set to the last value in [New Values][NewValues Property]; the second last item in [List][List Property] will be set to the second last value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyEmptyException][] | Thrown when [List][List Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] or [New Values][NewValues Property] is `null`. | + +## Remarks + +### Empty New Values + +If [New Values][NewValues Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValues Property]: {{< ref "#new-values" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-index-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-index-block-2.md new file mode 100644 index 000000000..091f1f048 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-index-block-2.md @@ -0,0 +1,146 @@ +--- +title: "Set Items At Index" +linkTitle: "Set Items At Index" +description: "Sets the items at the specified index of a List to new values." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemsAtIndexBlock`2)
+ +## Description + +Sets the items at the specified [Index][Index Property] of a [List][List Property] to [New Values][NewValues Property]. + +## Examples + +### Set the Items at the first Index (i.e. `0`) of a List to New Values + +This example will set the 2 items starting at index `0` of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Values][NewValues Property] | `($)NewValues`, with value `["Some Modified Text", 10]` | `($)NewValues` is a variable of type [IEnumerable][]<[dynamic][]> | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Setting the two items at index `0` of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", 10]` respectively, results in the variable `($)List` being updated to the following: + +```json +["Some Modified Text", 10, "Some More Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the items in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Values + +The [New Values][NewValues Property] to set the items at the specified [Index][Index Property] of [List][List Property] to. + +The number of items in [New Values][NewValues Property] determines the number of items that will be set at the end of [List][List Property]. One item means one item is set, two items means two items are set etc. + +The item at [Index][Index Property] of [List][List Property] will be set to the first value in [New Values][NewValues Property]; the item at [Index][Index Property] + `1` of [List][List Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Index + +The [Index][Index Property] to start setting the items at. This is an inclusive index, which means the item at the specified index will be included. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|-------------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [PropertyEmptyException][] | Thrown when [New Values][NewValues Property] contains no items. | +| [PropertyNullException][] | Thrown when [List][List Property] or [New Values][NewValues Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Index][Index Property] is less than `0` or greater than the count of items in [List][List Property] - `1`. | +| | Thrown when [Index][Index Property] + count of items in [New Values][NewValues Property] is greater than the count of items in the [List][List Property] - `1`. | + +## Remarks + +### Index is inclusive + +The [Index][Index Property] is an inclusive [index][Indexes], which means the item at the index will be included in the set items. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[NewValues Property]: {{< ref "#new-values" >}} +[Index Property]: {{< ref "#index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-indexes-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-indexes-block-2.md new file mode 100644 index 000000000..0c282b5a4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-at-indexes-block-2.md @@ -0,0 +1,146 @@ +--- +title: "Set Items At Indexes" +linkTitle: "Set Items At Indexes" +description: "Sets the items at each of the specified indexes of a List to new values." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemsAtIndexesBlock`2)
+ +## Description + +Sets the items at each of the specified [Indexes][Indexes Property] of a [List][List Property] to [New Values][NewValues Property]. + +## Examples + +### Sets items at the first and third Indexes (i.e. [`0`, `2`]) of a List to New Values + +This example will set items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", "Some More Modified Text"]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `["Some Text", 1, "Some More Text", 2]` | `($)List` is a variable of type [IList][]<[dynamic][]> | +| [New Values][NewValues Property] | `($)NewValues`, with value `["Some Modified Text", "Some More Modified Text"]` | `($)NewValues` is a variable of type [IEnumerable][]<[String][]> | +| [Indexes][Indexes Property] | `($)Indexes`, with value [`0`, `2`] | `($)Indexes` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Setting items at indexes `0` and `2` of `["Some Text", 1, "Some More Text", 2]` to `["Some Modified Text", "Some More Modified Text"]` respectively, results in the variable `($)List` being updated to the following: + +```json +["Some Modified Text", 1, "Some More Modified Text", 2] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set the items in. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### New Values + +The [New Values][NewValues Property] to set the items at the specified [Indexes][Indexes Property] of [List][List Property] to. + +The number of items in [New Values][NewValues Property] must match the number of items in [Indexes][Indexes Property]. + +The [List][List Property] item at the first index in [Indexes][Indexes Property] will be set to the first value in [New Values][NewValues Property]; the [List][List Property] item at the second index in [Indexes][Indexes Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Indexes + +The [Indexes][Indexes Property] of the items to set. + +Valid values are between and including `0` and the total count of items in the [List][List Property] - `1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[Int32][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Lists.SetItem.SetItemsWithValueBlock`2)
+ +## Description + +Sets all items matching a [Value][Value Property] in a [List][List Property] to a [New Value][NewValue Property]. + +## Examples + +### Set all items matching a Value in a List to a New Value + +This example will attempt to set all items matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Value][Value Property] | `($)Value`, with value `1` | `($)Value` is a variable of type [Int32][] | +| [New Value][NewValue Property] | `($)NewValue`, with value `10` | `($)NewValue` is a variable of type [Int32][] | + +#### Result + +Attempting to set all items matching the value `1` in `[1, 2, 3, 3, 2, 1]` to `10` results in the variable `($)List` being updated to the following: + +```json +[10, 2, 3, 3, 2, 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set all matching items in. + +Items are considered matching if they have the specified [Value][Value Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Value + +The [Value][Value Property] the items to set must match. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Value + +The [New Value][NewValue Property] to set all matching items in [List][List Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [InvalidPropertyValueException][] | Thrown when [Value][Value Property] or [New Value][NewValue Property] are `null` and [List][List Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [List][List Property] is `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### No items matching Value + +If [List][List Property] does not contain items matching the specified [Value][Value Property], there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Value Property]: {{< ref "#value" >}} +[NewValue Property]: {{< ref "#new-value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-with-values-block-2.md b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-with-values-block-2.md new file mode 100644 index 000000000..816568102 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Lists/set-item/set-items-with-values-block-2.md @@ -0,0 +1,157 @@ +--- +title: "Set Items With Values" +linkTitle: "Set Items With Values" +description: "Sets all items matching one of the specified values in a List to new values." +--- + +{{< figure src="/blocks/lists-set-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Lists.SetItem.SetItemsWithValuesBlock`2)
+ +## Description + +Set all items matching one of the specified [Values][Values Property] in a [List][List Property] to [New Values][NewValues Property]. + +## Examples + +### Set all items matching one of the specified Values in a List to New Values + +This example will attempt to set all items matching one of the values `[1, 2]` in `[1, 2, 3, 3, 2, 1]` to `[10, 20]` respectively. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [List][List Property] | `($)List`, with value `[1, 2, 3, 3, 2, 1]` | `($)List` is a variable of type [IList][]<[Int32][]> | +| [Values][Values Property] | `($)Values`, with value `[1, 2]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [NewValues][NewValues Property] | `($)NewValues`, with value `[10, 20]` | `($)NewValues` is a variable of type [IEnumerable][]<[Int32][]> | + +#### Result + +Attempting to set all items matching one of the values `[1, 2]` in `[1, 2, 3, 3, 2, 1]` to `[10, 20]` respectively, results in the variable `($)List` being updated to the following: + +```json +[10, 20, 3, 3, 20, 10] +``` + +*** + +## Properties + +### List + +The [List][List Property] to set all matching items in. + +Items are considered matching if they have one of the specified [Values][Values Property]. + +[List][List Property] can be any [IList][]<[TItem][]>, where [TItem][] represents the type of items in the [List][List Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)List` with no value | + +### Values + +The [Values][Values Property] the items to set must match one of. + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### New Values + +The [New Values][NewValues Property] to set the items matching the corresponding [Values][Values Property] in [List][List Property] to. + +The number of items in [New Values][NewValues Property] must match the number of items in [Values][Values Property]. + +[List][List Property] items matching the first value in [Values][Values Property] will be set to the first value in [New Values][NewValues Property]; [List][List Property] items matching the second value in [Values][Values Property] will be set to the second value in [New Values][NewValues Property] etc. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TItem][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [CannotModifyReadOnlyListException][] | Thrown when [List][List Property] is read-only. | +| [DuplicateValueException][] | Thrown when [Values][Values Property] contains duplicate values. | +| [PropertyItemCountException][] | Thrown when the count of items in [Values][Values Property] and the count of items in [New Values][NewValues Property] are not the same, or neither contain any items. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Values][Values Property] or [New Values][NewValues Property] are `null`. | + +## Remarks + +### Item Equality + +For information and examples of how it is determined whether an item matches a specified value, please see [Object Equality][]. + +### Empty List + +If [List][List Property] is empty (i.e. `[]`) there is nothing to set, so no operation is performed. + +### No items matching a specified value in Values + +If [List][List Property] does not contain items matching one of the specified [Values][Values Property], there is nothing to set for that value. + +### No items matching Values + +If [List][List Property] does not contain items matching any of the specified [Values][Values Property], there is nothing to set, so no operation is performed. + +### Defining lists using literal syntax + +For information about how to define lists using literal syntax, see [Create a List<TItem>][]. + +### Defining lists using expression syntax + +For information about how to define lists using expression syntax, see [Create a List<TItem>][]. + +### Lists containing items of a single data type vs multiple data types + +For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see [Lists][]. + +[List Property]: {{< ref "#list" >}} +[Values Property]: {{< ref "#values" >}} +[NewValues Property]: {{< ref "#new-values" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Create a List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Lists]: {{< url path="Cortex.Reference.DataTypes.MostCommon.Lists" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[DuplicateValueException]: {{< url path="Cortex.Reference.Exceptions.Lists.DuplicateValueException.MainDoc" >}} +[PropertyItemCountException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyItemCountException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/PowerShell/_index.md b/content/en/docs/2023.9/Reference/Blocks/PowerShell/_index.md new file mode 100644 index 000000000..7bb3eb21b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/PowerShell/_index.md @@ -0,0 +1,5 @@ +--- +title: "PowerShell" +linkTitle: "PowerShell" +description: "Blocks related to working with Windows PowerShell and PowerShell Core." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/_index.md b/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/_index.md new file mode 100644 index 000000000..abc8da99e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute PowerShell Script" +linkTitle: "Execute PowerShell Script" +description: "Blocks related to executing PowerShell scripts with Windows PowerShell and PowerShell Core." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/execute-powershell-script-block-1.md b/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/execute-powershell-script-block-1.md new file mode 100644 index 000000000..dee8d299a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/PowerShell/execute-powershell-script/execute-powershell-script-block-1.md @@ -0,0 +1,392 @@ +--- +title: "Execute PowerShell Script" +linkTitle: "Execute PowerShell Script" +description: "Executes a PowerShell script on the specified host." +--- + +{{< figure src="/blocks/powershell-execute-powershell-script-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScriptBlock`1)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Connects to a host using the specified [PowerShell Session Details][PowerShell Session Details Property], and executes a [Script][Script Property], returning the [Outputs][Outputs Property] and [Records][Records Property]. + +[Close Session][Close Session Property] can be specified to choose whether the session on the host is closed or is kept open for use on subsequent Execute PowerShell Script blocks. + +## Examples + +### Execute a Script using PowerShellWinRMSessionDetails + +This example will execute a script on the server with the following details: + +- Host - `"host.domain.com"` +- Port - `5986` +- UseSsl - `true` + +The host can be connected to with the following credentials: + +- Domain - `"domain.com"` +- Username - `"username"` +- Password - `"password"` + +The server that the script will be executed on contains a text file in the following location `C:\Folder\Example.txt`, the file contains the following text before the script is executed: + +`"This is the content of the file located on the host the script is running on."` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Script][Script Property] | `($)Script` with value `"Get-Content \"C:\\Folder\\Example.txt\""` | `($)Script` is a variable of type [String][] | +| [Parameters][Parameters Property] | `($)Parameters` with no value | `($)Parameters` is a variable of type [Dictionary][]<[String][], [dynamic][]> | +| [PowerShell Session Details][PowerShell Session Details Property] | `($)PowerShellSessionDetails` with value `{"ServerDetails": {"Host": "host.domain.com", "Port": 5986, "UseSsl": "true"}, "Credentials": {"Domain": "domain.com", "Username": "username", "Password": "encryptedPassword"}}`(Cortex.Blocks.Text.ConvertTo.ConvertToCamelCaseBlock)
+ +## Description + +Converts [Text][Text Property] to camel case. + +Converting to camel case will result in all words (except the first) having their first letter capitalized, all other letters lower cased, and all spaces and punctuation being removed (e.g. `"TEXT to convert to camel-case!"` will be converted to `"textToConvertToCamelCase"`). + +## Examples + +### Text converted to camel case + +This example will convert `"The quick brown fox jumps over the lazy dog"` to camel case. + +It performs a [culture-insensitive][InvariantCulture] conversion of the text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Culture Info][CultureInfo Property] | `($)CultureInfo`, with value `CultureInfo.InvariantCulture` | `($)CultureInfo` is a variable of type [CultureInfo][] | + +#### Result + +Converting `"The quick brown fox jumps over the lazy dog"` to camel case will result in the variable `($)Text` being updated to the following: + +```json +"theQuickBrownFoxJumpsOverTheLazyDog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to camel case. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Culture Info + +The [Culture Info][CultureInfo Property] used to perform the conversion of the [Text][Text Property]. + +For information about the [supported values][CultureInfos] for the [Culture Info][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +| | | +|--------------------|---------------------------| +| Data Type | [CultureInfo][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when the culture identifier of the [Culture Info][CultureInfo Property] is invalid (e.g. `new CultureInfo("InvalidCultureIdentifier")`). See [Value Is Invalid][]. | + +## Remarks + +### Culture Info + +For information about the [supported values][CultureInfos] for the [CultureInfo][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +### Null Culture Info + +If [Culture Info][CultureInfo Property] is `null`, it will be set to `CultureInfo.InvariantCulture`. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] converted to camel case and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[CultureInfo Property]: {{< ref "#culture-info" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Casing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.MainDoc" >}} +[CultureInfos]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.CultureInfo.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.DataTypes.MostCommon.InvariantCulture" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-lower-case-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-lower-case-block.md new file mode 100644 index 000000000..936c9a451 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-lower-case-block.md @@ -0,0 +1,120 @@ +--- +title: "Convert To Lower Case" +linkTitle: "Convert To Lower Case" +description: "Converts text to lower case (e.g. `\"lowercase\"`)." +--- + +{{< figure src="/blocks/text-convert-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.ConvertTo.ConvertToLowerCaseBlock)
+ +## Description + +Converts [Text][Text Property] to lower case. + +Converting to lower case will result in all letters being lower cased; spaces and punctuation will be preserved (e.g. `"TEXT to convert to lower-case!"` will be converted to `"text to convert to lower-case!"`). + +## Examples + +### Text converted to lower case + +This example will convert `"The quick brown fox jumps over the lazy dog"` to lower case. + +It performs a [culture-insensitive][InvariantCulture] conversion of the text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Culture Info][CultureInfo Property] | `($)CultureInfo`, with value `CultureInfo.InvariantCulture` | `($)CultureInfo` is a variable of type [CultureInfo][] | + +#### Result + +Converting `"The quick brown fox jumps over the lazy dog"` to lower case will result in the variable `($)Text` being updated to the following: + +```json +"the quick brown fox jumps over the lazy dog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to lower case. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Culture Info + +The [Culture Info][CultureInfo Property] used to perform the conversion of the [Text][Text Property]. + +For information about the [supported values][CultureInfos] for the [Culture Info][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +| | | +|--------------------|---------------------------| +| Data Type | [CultureInfo][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when the culture identifier of the [Culture Info][CultureInfo Property] is invalid (e.g. `new CultureInfo("InvalidCultureIdentifier")`). See [Value Is Invalid][]. | + +## Remarks + +### Culture Info + +For information about the [supported values][CultureInfos] for the [CultureInfo][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +### Null Culture Info + +If [Culture Info][CultureInfo Property] is `null`, it will be set to `CultureInfo.InvariantCulture`. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] converted to lower case and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[CultureInfo Property]: {{< ref "#culture-info" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Casing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.MainDoc" >}} +[CultureInfos]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.CultureInfo.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.DataTypes.MostCommon.InvariantCulture" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-pascal-case-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-pascal-case-block.md new file mode 100644 index 000000000..4d91592a6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-pascal-case-block.md @@ -0,0 +1,120 @@ +--- +title: "Convert To Pascal Case" +linkTitle: "Convert To Pascal Case" +description: "Converts text to pascal case (e.g. `\"PascalCase\"`)." +--- + +{{< figure src="/blocks/text-convert-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.ConvertTo.ConvertToPascalCaseBlock)
+ +## Description + +Converts [Text][Text Property] to pascal case. + +Converting to pascal case will result in all words having their first letter capitalized, all other letters lower cased, and all spaces and punctuation being removed (e.g. `"TEXT to convert to pascal-case!"` will be converted to `"TextToConvertToPascalCase"`). + +## Examples + +### Text converted to pascal case + +This example will convert `"The quick brown fox jumps over the lazy dog"` to pascal case. + +It performs a [culture-insensitive][InvariantCulture] conversion of the text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Culture Info][CultureInfo Property] | `($)CultureInfo`, with value `CultureInfo.InvariantCulture` | `($)CultureInfo` is a variable of type [CultureInfo][] | + +#### Result + +Converting `"The quick brown fox jumps over the lazy dog"` to pascal case will result in the variable `($)Text` being updated to the following: + +```json +"TheQuickBrownFoxJumpsOverTheLazyDog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to pascal case. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Culture Info + +The [Culture Info][CultureInfo Property] used to perform the conversion of the [Text][Text Property]. + +For information about the [supported values][CultureInfos] for the [Culture Info][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +| | | +|--------------------|---------------------------| +| Data Type | [CultureInfo][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when the culture identifier of the [Culture Info][CultureInfo Property] is invalid (e.g. `new CultureInfo("InvalidCultureIdentifier")`). See [Value Is Invalid][]. | + +## Remarks + +### Culture Info + +For information about the [supported values][CultureInfos] for the [CultureInfo][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +### Null Culture Info + +If [Culture Info][CultureInfo Property] is `null`, it will be set to `CultureInfo.InvariantCulture`. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] converted to pascal case and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[CultureInfo Property]: {{< ref "#culture-info" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Casing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.MainDoc" >}} +[CultureInfos]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.CultureInfo.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.DataTypes.MostCommon.InvariantCulture" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-title-case-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-title-case-block.md new file mode 100644 index 000000000..cd57b8623 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-title-case-block.md @@ -0,0 +1,120 @@ +--- +title: "Convert To Title Case" +linkTitle: "Convert To Title Case" +description: "Converts text to title case (e.g. `\"Title Case\"`)." +--- + +{{< figure src="/blocks/text-convert-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.ConvertTo.ConvertToTitleCaseBlock)
+ +## Description + +Converts [Text][Text Property] to title case. + +Converting to title case will result in all words having their first letter capitalized and all other letters lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased; spaces and punctuation will be preserved (e.g. `"TEXT to convert to title-case!"` will be converted to `"TEXT To Convert To Title-Case!"`). + +## Examples + +### Text converted to title case + +This example will convert `"The quick brown fox jumps over the lazy dog"` to title case. + +It performs a [culture-insensitive][InvariantCulture] conversion of the text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Culture Info][CultureInfo Property] | `($)CultureInfo`, with value `CultureInfo.InvariantCulture` | `($)CultureInfo` is a variable of type [CultureInfo][] | + +#### Result + +Converting `"The quick brown fox jumps over the lazy dog"` to title case will result in the variable `($)Text` being updated to the following: + +```json +"The Quick Brown Fox Jumps Over The Lazy Dog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to title case. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Culture Info + +The [Culture Info][CultureInfo Property] used to perform the conversion of the [Text][Text Property]. + +For information about the [supported values][CultureInfos] for the [Culture Info][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +| | | +|--------------------|---------------------------| +| Data Type | [CultureInfo][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when the culture identifier of the [Culture Info][CultureInfo Property] is invalid (e.g. `new CultureInfo("InvalidCultureIdentifier")`). See [Value Is Invalid][]. | + +## Remarks + +### Culture Info + +For information about the [supported values][CultureInfos] for the [CultureInfo][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +### Null Culture Info + +If [Culture Info][CultureInfo Property] is `null`, it will be set to `CultureInfo.InvariantCulture`. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] converted to title case and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[CultureInfo Property]: {{< ref "#culture-info" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Casing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.MainDoc" >}} +[CultureInfos]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.CultureInfo.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.DataTypes.MostCommon.InvariantCulture" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-upper-case-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-upper-case-block.md new file mode 100644 index 000000000..5c92f7f24 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Convert-To/convert-to-upper-case-block.md @@ -0,0 +1,120 @@ +--- +title: "Convert To Upper Case" +linkTitle: "Convert To Upper Case" +description: "Converts text to upper case (e.g. `\"UPPERCASE\"`)." +--- + +{{< figure src="/blocks/text-convert-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.ConvertTo.ConvertToUpperCaseBlock)
+ +## Description + +Converts [Text][Text Property] to upper case. + +Converting to upper case will result in all letters being upper cased; spaces and punctuation will be preserved (e.g. `"TEXT to convert to upper-case!"` will be converted to `"TEXT TO CONVERT TO UPPER-CASE!"`). + +## Examples + +### Text converted to upper case + +This example will convert `"The quick brown fox jumps over the lazy dog"` to upper case. + +It performs a [culture-insensitive][InvariantCulture] conversion of the text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Culture Info][CultureInfo Property] | `($)CultureInfo`, with value `CultureInfo.InvariantCulture` | `($)CultureInfo` is a variable of type [CultureInfo][] | + +#### Result + +Converting `"The quick brown fox jumps over the lazy dog"` to upper case will result in the variable `($)Text` being updated to the following: + +```json +"THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to upper case. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Culture Info + +The [Culture Info][CultureInfo Property] used to perform the conversion of the [Text][Text Property]. + +For information about the [supported values][CultureInfos] for the [Culture Info][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +| | | +|--------------------|---------------------------| +| Data Type | [CultureInfo][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when the culture identifier of the [Culture Info][CultureInfo Property] is invalid (e.g. `new CultureInfo("InvalidCultureIdentifier")`). See [Value Is Invalid][]. | + +## Remarks + +### Culture Info + +For information about the [supported values][CultureInfos] for the [CultureInfo][CultureInfo Property] property and examples of how it affects casing rules, please see [Casing][]. + +### Null Culture Info + +If [Culture Info][CultureInfo Property] is `null`, it will be set to `CultureInfo.InvariantCulture`. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] converted to upper case and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[CultureInfo Property]: {{< ref "#culture-info" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Casing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.MainDoc" >}} +[CultureInfos]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Casing.CultureInfo.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.DataTypes.MostCommon.InvariantCulture" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/_index.md new file mode 100644 index 000000000..b1f69b98a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Index(es) of Text" +linkTitle: "Get Index(es) of Text" +description: "Get the index for the specified occurrence of text, or the indexes of all occurrences of text contained in another text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-index-of-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-index-of-text-block.md new file mode 100644 index 000000000..15d0642aa --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-index-of-text-block.md @@ -0,0 +1,335 @@ +--- +title: "Get Index Of Text" +linkTitle: "Get Index Of Text" +description: "Gets the index of the specified occurrence of a text in another text." +--- + +{{< figure src="/blocks/text-get-index-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetIndex.GetIndexOfTextBlock)
+ +## Description + +Gets the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Get the Index of the first Occurrence of Text To Find (Ordinal) + +This example will get the index of the first occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"The"` | `($)TextToFind` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means get the index of the first occurrence; `2` means second etc. + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Index` will be updated to the following: + +```json +0 +``` + +where `0` indicates the index of the first character of the first and only occurrence matching `"The"`. + +*** + +### Get the Index of the last Occurrence of Text To Find (Ordinal Ignore Case) + +This example will get the index of the last occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"The"` | `($)TextToFind` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `-1` means get the index of the last occurrence; `2` means second last etc. + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second and last occurrence is `"the"`. Therefore, the variable `($)Index` will be updated to the following: + +```json +31 +``` + +where `31` indicates the index of the first character of the last matching occurrence, `"the"`. + +*** + +### Text does not contain Text To Find + +This example will attempt to get the index of the first occurrence of `"slow"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"slow"` | `($)TextToFind` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` does not contain the text `"slow"`, so the index cannot be found. Therefore, the variable `($)Index` will be updated to the following: + +```json +-1 +``` + +where `-1` indicates that there are no matching occurrences. + +*** + +### Get the Index of the first Occurrence matching the pattern in Text To Find + +This example will get the index of the first occurrence of text matching the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"?he"` | `($)TextToFind` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means get the index of the first occurrence; `2` means second etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the pattern `"?he"`; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Index` will be updated to the following: + +```json +0 +``` + +where `0` indicates the index of the first character of the first occurrence matching the pattern `"?he"`. + +*** + +### Get the Index of the last Occurrence matching the regex in Text To Remove + +This example will get the index of the last occurrence of text matching the regex `"(fox|dog)"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"(fox\|dog)"` | `($)TextToFind` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Index][Index Property] | `($)Index`, with no value | `($)Index` is a variable that will be set to an [Int32][] value | + +#### Result + +An [Occurrence][Occurrence Property] of `-1` means get the index of the last occurrence; `2` means second last etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the regex `"(fox|dog)"`; the first occurrence is `"fox"` and the second and last occurrence is `"dog"`. Therefore, the variable `($)Index` will be updated to the following: + +```json +40 +``` + +where `0` indicates the index of the first character of the last occurrence matching the regex `"(fox|dog)"`. + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] the [Index][Index Property] of the specified [Occurrence][Occurrence Property] of, in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Occurrence + +The specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Find][TextToFind Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Index + +[Int32][] indicating the [Index][Index Property] of the first character of the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in [Text][Text Property]. + +If there is no specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in [Text][Text Property], the specified variable will be set to `-1`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Index` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Find][TextToFind Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), the variable specified in the [Index][Index Property] property is set to `-1`. + +### Null or empty Text To Find + +If [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), the variable specified in the [Index][Index Property] property is set to `-1`. + +### Occurrence is zero + +If the [Occurrence][Occurrence Property] is set to `0`, the variable specified in the [Index][Index Property] property is set to `-1`. + +### Occurrence of Text To Find not found + +If the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] is not found in [Text][Text Property], the variable specified in the [Index][Index Property] property is set to `-1`. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Index Property]: {{< ref "#index" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-indexes-of-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-indexes-of-text-block.md new file mode 100644 index 000000000..cd467c0af --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Index/get-indexes-of-text-block.md @@ -0,0 +1,303 @@ +--- +title: "Get Indexes Of Text" +linkTitle: "Get Indexes Of Text" +description: "Gets the indexes of all occurrences of a text in another text." +--- + +{{< figure src="/blocks/text-get-index-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetIndex.GetIndexesOfTextBlock)
+ +## Description + +Gets the [Indexes][Indexes Property] of all occurrences of [Text To Find][TextToFind Property] in [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Get Indexes of all occurrences of Text To Find (Ordinal) + +This example will get the indexes of all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"The"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Indexes` will be updated to the following: + +```json +[0] +``` + +where `0` indicates the index of the first character of the matching `"The"` occurrence. + +*** + +### Get Indexes of all occurrences of Text To Find (Ordinal Ignore Case) + +This example will get the indexes of all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"The"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Indexes` will be updated to the following: + +```json +[0, 31] +``` + +where `0` indicates the index of the first character of the matching `"The"` occurrence, and `31` indicates the index of the first character of the matching `"the"` occurrence. + +*** + +### Text does not contain Text To Find + +This example will attempt to get the indexes of all occurrences of `"slow"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"slow"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` does not contain the text `"slow"`, so the index cannot be found. Therefore, the variable `($)Indexes` will be updated to the following: + +```json +[-1] +``` + +where `-1` indicates that there are no matching occurrences. + +*** + +### Get Indexes of all occurrences matching the pattern in Text To Find + +This example will get the indexes of all occurrences of text matching the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"?he"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the pattern `"?he"`; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Indexes` will be updated to the following: + +```json +[0, 31] +``` + +where `0` indicates the index of the first character of the matching `"The"` occurrence, and `31` indicates the index of the first character of the matching `"the"` occurrence. + +*** + +### Get Indexes of all occurrences matching the regex in Text To Remove + +This example will get the indexes of all occurrences of text matching the regex `"(fox|dog)"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"(fox\|dog)"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Indexes][Indexes Property] | `($)Indexes`, with no value | `($)Indexes` is a variable that will be set to an [IList][]<[Int32][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the regex `"(fox|dog)"`; the first occurrence is `"fox"` and the second and last occurrence is `"dog"`. Therefore, the variable `($)Indexes` will be updated to the following: + +```json +[16, 40] +``` + +where `16` indicates the index of the first character of the matching `"fox"` occurrence, and `40` indicates the index of the first character of the matching `"dog"` occurrence. + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Indexes][Indexes Property] of all occurrences of [Text To Find][TextToFind Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] the [Indexes][Indexes Property] of all occurrences of, in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Find][TextToFind Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Indexes + +[IList][]<[Int32][]> containing the [Indexes][Indexes Property] of the first character of each occurrence of [Text To Find][TextToFind Property] in [Text][Text Property]. + +If there are no occurrences of [Text To Find][TextToFind Property] in [Text][Text Property], the specified variable will be set to `[-1]`. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[Int32][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Indexes` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Find][TextToFind Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), the variable specified in the [Indexes][Indexes Property] property is set to `[-1]`. + +### Null or empty Text To Find + +If [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), the variable specified in the [Indexes][Indexes Property] property is set to `[-1]`. + +### Text To Find not found + +If [Text To Find][TextToFind Property] is not found in [Text][Text Property], the variable specified in the [Indexes][Indexes Property] property is set to `[-1]`. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Indexes Property]: {{< ref "#indexes" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/_index.md new file mode 100644 index 000000000..0602a8e34 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Length" +linkTitle: "Get Length" +description: "Get the length of a text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/get-length-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/get-length-block.md new file mode 100644 index 000000000..0a280a4ae --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/Get-Length/get-length-block.md @@ -0,0 +1,89 @@ +--- +title: "Get Length" +linkTitle: "Get Length" +description: "Gets the length of a given text." +--- + +{{< figure src="/blocks/text-get-length-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetLength.GetLengthBlock)
+ +## Description + +Gets the [Length][Length Property] of a given [Text][Text Property]. + +## Examples + +### Get the Length of a given Text + +This example will get the length of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Length][Length Property] | `($)Length`, with no value | `($)Length` is a variable that will be set to an [Int32][] | + +#### Result + +Getting the length of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)Length` being updated to the following: + +```json +26 +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Length][Length Property] of. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Length + +The [Length][Length Property] of the [Text][Text Property] (i.e. the number of characters it contains). + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Length` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) the variable specified in the [Length][Length Property] property will be set to `0`. + +[Text Property]: {{< ref "#text" >}} +[Length Property]: {{< ref "#length" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/_index.md new file mode 100644 index 000000000..cfd3af806 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Text" +linkTitle: "Text" +description: "Blocks related to working with Text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/add-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/_index.md new file mode 100644 index 000000000..bafeeb0f4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Add Text" +linkTitle: "Add Text" +description: "Add text to another text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-after-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-after-index-block.md new file mode 100644 index 000000000..d7c66903e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-after-index-block.md @@ -0,0 +1,142 @@ +--- +title: "Add Text After Index" +linkTitle: "Add Text After Index" +description: "Adds text to another text after a given index." +--- + +{{< figure src="/blocks/text-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.AddText.AddTextAfterIndexBlock)
+ +## Description + +Adds [Text To Add][TextToAdd Property] to another [Text][Text Property] after the given [Index][Index Property]. + +## Examples + +### Add Text To Add to another Text after the given Index + +This example will add `"|"` after `"A"` (which is at index `0`) in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +`"A"` is at index `0` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, adding `"|"` after index `0` results in the variable `($)Text` being updated to the following: + +```json +"A|BCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +### Add null or empty Text To Add to another Text after the given Index + +This example will try to add `null` or `""` after `"A"` (which is at index `0`) in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `null` or `""` | `($)TextToAdd` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `null` or `""` performs no operation as there is nothing to add, so the variable `($)Text` will remain as follows: + +```json +"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] where the [Text To Add][TextToAdd Property] is added. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Add + +The [Text To Add][TextToAdd Property] to the [Text][Text Property] after the given [Index][Index Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Index + +The [Index][Index Property] to add the [Text To Add][TextToAdd Property] after. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Null or empty Text To Add + +If [Text To Add][TextToAdd Property] is `null` or empty (i.e. `""`) nothing is added to [Text][Text Property]. See [Example][NullOrEmptyTextToAdd Example] above. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text To Add][TextToAdd Property] added in the correct place and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[TextToAdd Property]: {{< ref "#text-to-add" >}} +[Index Property]: {{< ref "#index" >}} + +[NullOrEmptyTextToAdd Example]: {{< ref "#add-null-or-empty-text-to-add-to-another-text-after-the-given-index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-beginning-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-beginning-block.md new file mode 100644 index 000000000..8cdcefb62 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-beginning-block.md @@ -0,0 +1,143 @@ +--- +title: "Add Text At Beginning" +linkTitle: "Add Text At Beginning" +description: "Adds text at the beginning of another text." +--- + +{{< figure src="/blocks/text-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.AddText.AddTextAtBeginningBlock)
+ +## Description + +Adds [Text To Add][TextToAdd Property] at the beginning of another [Text][Text Property]. + +## Examples + +### Add Text To Add at the beginning of another Text + +This example will add `"|"` at the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `"|"` at the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)Text` being updated to the following: + +```json +"|ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +### Add Text To Add at the beginning of a null or empty Text + +This example will try to add `"|"` at the beginning of `null` or `""`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` or `""` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `"|"` to `null` or `""` results in the variable `($)Text` being updated to the following: + +```json +"|" +``` + +*** + +### Add null or empty Text To Add at the beginning of another Text + +This example will try to add `null` or `""` at the beginnning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `null` or `""` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `null` or `""` performs no operation as there is nothing to add, so the variable `($)Text` will remain as follows: + +```json +"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] where the [Text To Add][TextToAdd Property] is added. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Add + +The [Text To Add][TextToAdd Property] at the beginning of the [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) it is replaced with the [Text To Add][TextToAdd Property]. See [Example][NullOrEmptyText Example] above. + +### Null or empty Text To Add + +If [Text To Add][TextToAdd Property] is `null` or empty (i.e. `""`) nothing is added to [Text][Text Property]. See [Example][NullOrEmptyTextToAdd Example] above. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text To Add][TextToAdd Property] added in the correct place and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[TextToAdd Property]: {{< ref "#text-to-add" >}} + +[NullOrEmptyText Example]: {{< ref "#add-text-to-add-at-the-beginning-of-a-null-or-empty-text" >}} +[NullOrEmptyTextToAdd Example]: {{< ref "#add-null-or-empty-text-to-add-at-the-beginning-of-another-text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-end-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-end-block.md new file mode 100644 index 000000000..20b61514b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-at-end-block.md @@ -0,0 +1,143 @@ +--- +title: "Add Text At End" +linkTitle: "Add Text At End" +description: "Adds text at the end of another text." +--- + +{{< figure src="/blocks/text-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.AddText.AddTextAtEndBlock)
+ +## Description + +Adds [Text To Add][TextToAdd Property] at the end of another [Text][Text Property]. + +## Examples + +### Add Text To Add at the end of another Text + +This example will add `"|"` at the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `"|"` at the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)Text` being updated to the following: + +```json +"ABCDEFGHIJKLMNOPQRSTUVWXYZ|" +``` + +*** + +### Add Text To Add at the end of a null or empty Text + +This example will try to add `"|"` at the end of `null` or `""`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` or `""` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `"|"` to `null` or `""` results in the variable `($)Text` being updated to the following: + +```json +"|" +``` + +*** + +### Add null or empty Text To Add at the end of another Text + +This example will try to add `null` or `""` at the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `null` or `""` | `($)TextToAdd` is a variable of type [String][] | + +#### Result + +Adding `null` or `""` performs no operation as there is nothing to add, so the variable `($)Text` will remain as follows: + +```json +"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] where the [Text To Add][TextToAdd Property] is added. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Add + +The [Text To Add][TextToAdd Property] at the end of the [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) it is replaced with the [Text To Add][TextToAdd Property]. See [Example][NullOrEmptyText Example] above. + +### Null or empty Text To Add + +If [Text To Add][TextToAdd Property] is `null` or empty (i.e. `""`) nothing is added to [Text][Text Property]. See [Example][NullOrEmptyTextToAdd Example] above. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text To Add][TextToAdd Property] added in the correct place and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[TextToAdd Property]: {{< ref "#text-to-add" >}} + +[NullOrEmptyText Example]: {{< ref "#add-text-to-add-at-the-end-of-a-null-or-empty-text" >}} +[NullOrEmptyTextToAdd Example]: {{< ref "#add-null-or-empty-text-to-add-at-the-end-of-another-text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-before-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-before-index-block.md new file mode 100644 index 000000000..cb7b27598 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/add-text/add-text-before-index-block.md @@ -0,0 +1,144 @@ +--- +title: "Add Text Before Index" +linkTitle: "Add Text Before Index" +description: "Adds text to another text before the specified index." +--- + +{{< figure src="/blocks/text-add-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.AddText.AddTextBeforeIndexBlock)
+ +## Description + +Adds [Text To Add][TextToAdd Property] to another [Text][Text Property] before the specified [Index][Index Property]. + +## Examples + +### Add Text To Add to another Text before the given Index + +This example will add `"|"` before `"A"` (which is at index `0`) in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `"\|"` | `($)TextToAdd` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +`"A"` is at index `0` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, adding `"|"` before index `0` results in the variable `($)Text` being updated to the following: + +```json +"|ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +### Add null or empty Text To Add to another Text before the given Index + +This example will try to add `null` or `""` before `"A"` (which is at index `0`) in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Text To Add][TextToAdd Property] | `($)TextToAdd`, with value `null` or `""` | `($)TextToAdd` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `0` | `($)Index` is a variable of type [Int32][] | + +#### Result + +Adding `null` or `""` performs no operation as there is nothing to add, so the variable `($)Text` will remain as follows: + +```json +"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] where the [Text To Add][TextToAdd Property] is added. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Add + +The [Text To Add][TextToAdd Property] to the [Text][Text Property] before the given [Index][Index Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Index + +The [Index][Index Property] to add the [Text To Add][TextToAdd Property] before. + +For information about what an index is, please see [Indexes]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Null or empty Text To Add + +If [Text To Add][TextToAdd Property] is `null` or empty (i.e. `""`) nothing is added to [Text][Text Property]. See [Example][NullOrEmptyTextToAdd Example] above. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text To Add][TextToAdd Property] added in the correct place and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[TextToAdd Property]: {{< ref "#text-to-add" >}} +[Index Property]: {{< ref "#index" >}} + +[NullOrEmptyTextToAdd Example]: {{< ref "#add-null-or-empty-text-to-add-to-another-text-before-the-given-index" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/_index.md new file mode 100644 index 000000000..a39909591 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Contains Text" +linkTitle: "Contains Text" +description: "Check if text is contained in another text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/contains-all-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/contains-all-text-block.md new file mode 100644 index 000000000..304443329 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/contains-text/contains-all-text-block.md @@ -0,0 +1,261 @@ +--- +title: "Contains All Text" +linkTitle: "Contains All Text" +description: "Checks if text contains all of the texts in a given set of texts." +--- + +{{< figure src="/blocks/text-contains-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.ContainsText.ContainsAllTextBlock)
+ +## Description + +Checks if [Text][Text Property] contains all of the texts in a given set of [Texts To Find][TextsToFind Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check. + +## Examples + +### Text contains all of the texts in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains all of the texts in `["The", "quick", "brown", "fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["The", "quick", "brown", "fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains All Text][ContainsAllText Property] | `($)ContainsAllText`, with no value | `($)ContainsAllText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains all of the texts in `["The", "quick", "brown", "fox"]`. Therefore, the variable `($)ContainsAllText` will be updated to the following: + +```json +true +``` + +*** + +### Text does not contain all of the texts in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains all of the texts in `["the", "slow", "brown", "fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["the", "slow", "brown", "fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains All Text][ContainsAllText Property] | `($)ContainsAllText`, with no value | `($)ContainsAllText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` does not contain all of the texts in `["the", "slow", "brown", "fox"]`; `"slow"` is missing, and `"the"` does not match `"The"` as the specified [Comparison Type][ComparisonType Property] uses case-sensitive matching. Therefore, the variable `($)ContainsAllText` will be updated to the following: + +```json +false +``` + +*** + +### Text contains text that matches all of the patterns in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches all of the patterns in `["?he", "?uick", "*?own", "fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["?he", "?uick", "*?own", "fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains All Text][ContainsAllText Property] | `($)ContainsAllText`, with no value | `($)ContainsAllText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains text that matches all of the patterns in `["?he", "?uick", "*?own", "fox"]`. Therefore, the variable `($)ContainsAllText` will be updated to the following: + +```json +true +``` + +*** + +### Text contains text that matches all of the regexes in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches all of the regexes in `["^The", "(quick|fast)", "b.* ", "(fox|Fox)"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["^The", "(quick\|fast)", "b.* ", "(fox\|Fox)"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains All Text][ContainsAllText Property] | `($)ContainsAllText`, with no value | `($)ContainsAllText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains text that matches all of the regexes in `["^The", "(quick|fast)", "b.* ", "(fox|Fox)"]`. Therefore, the variable `($)ContainsAllText` will be updated to the following: + +```json +true +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check whether it contains all of the texts in the given set of [Texts To Find][TextsToFind Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Texts To Find + +The set of [Texts To Find][TextsToFind Property] to check are all contained in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Text.ContainsText.ContainsAnyTextBlock)
+ +## Description + +Checks if [Text][Text Property] contains any of the texts in a given set of [Texts To Find][TextsToFind Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check. + +## Examples + +### Text contains any of the texts in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains at least one of the texts in `["The", "fast", "red", "fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["The", "fast", "red", "fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Any Text][ContainsAnyText Property] | `($)ContainsAnyText`, with no value | `($)ContainsAnyText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains the text `"The"` and `"fox"` in `["The", "fast", "red", "fox"]`. Therefore, the variable `($)ContainsAnyText` will be updated to the following: + +```json +true +``` + +*** + +### Text does not contain any of the texts in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains at least one of the texts in `["the", "slow", "red", "Fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["the", "slow", "red", "Fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Any Text][ContainsAnyText Property] | `($)ContainsAnyText`, with no value | `($)ContainsAnyText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` does not contain any of the texts in `["the", "slow", "red", "Flow"]`; `"slow"` and `"red"` are both missing, and `"the"` and `"Fox"` do not match `"The"` and `"fox"` respectively as the specified [Comparison Type][ComparisonType Property] uses case-sensitive matching. Therefore, the variable `($)ContainsAnyText` will be updated to the following: + +```json +false +``` + +*** + +### Text contains text that matches any of the patterns in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches any of the patterns in `["?he", "Q?ick", "B*?wn", "Fox"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["?he", "Q?ick", "B*?wn", "Fox"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Any Text][ContainsAnyText Property] | `($)ContainsAnyText`, with no value | `($)ContainsAnyText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains text that matches one of the patterns in `["?he", "Q?ick", "B*?wn", "Fox"]`; `"?he"` matches `"The"` and `"the"`. Therefore, the variable `($)ContainsAnyText` will be updated to the following: + +```json +true +``` + +*** + +### Text contains text that matches any of the regexes in Texts To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches any of the regexes in `["^The", "(Quick|Fast)", "b.* ", "(fox|Fox)$"]`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Texts To Find][TextsToFind Property] | `($)TextsToFind`, with value `["^The", "(Quick\|Fast)", "b.* ", "(fox\|Fox)$"]` | `($)TextsToFind` is a variable of type [IEnumerable][]<[String][]> | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Any Text][ContainsAnyText Property] | `($)ContainsAnyText`, with no value | `($)ContainsAnyText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains text that matches any of the regexes in `["^The", "(Quick|Fast)", "b.* ", "(fox|Fox)$"]`; `"^The"` matches `"The"` at the start of the sentence. Therefore, the variable `($)ContainsAnyText` will be updated to the following: + +```json +true +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check whether it contains any of the texts in the given set of [Texts To Find][TextsToFind Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Texts To Find + +The set of [Texts To Find][TextsToFind Property] to check any are contained in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[String][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Text.ContainsText.ContainsTextBlock)
+ +## Description + +Checks if [Text][Text Property] contains [Text To Find][TextToFind Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check. + +## Examples + +### Text contains Text To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains the text `"quick brown fox"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"quick brown fox"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Text][ContainsText Property] | `($)ContainsText`, with no value | `($)ContainsText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains the text `"quick brown fox"`. Therefore, the variable `($)ContainsText` will be updated to the following: + +```json +true +``` + +*** + +### Text does not contain Text To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains the text `"quick red fox"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"quick red fox"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Text][ContainsText Property] | `($)ContainsText`, with no value | `($)ContainsText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` does not contain `"quick red fox"`. Therefore, the variable `($)ContainsText` will be updated to the following: + +```json +false +``` + +*** + +### Text contains text that matches the pattern in Text To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches the pattern `"*?he"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"?he"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Text][ContainsText Property] | `($)ContainsText`, with no value | `($)ContainsText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` and `"the"` that matches the pattern `"?he"`. Therefore, the variable `($)ContainsText` will be updated to the following: + +```json +true +``` + +*** + +### Text contains text that matches the regex in Text To Find + +This example will check whether `"The quick brown fox jumps over the lazy dog"` contains text that matches the regex `"^The"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `"^The"` | `($)TextToFind` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Contains Text][ContainsText Property] | `($)ContainsText`, with no value | `($)ContainsText` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` at the start of the sentence that matches the regex `"^The"`. Therefore, the variable `($)ContainsText` will be updated to the following: + +```json +true +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check whether it contains [Text To Find][TextToFind Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Find][TextToFind Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether [Text To Find][TextToFind Property] is contained in [Text][Text Property] + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Contains Text + +The result of the contains text check. + +If [Text To Find][TextToFind Property] is contained in [Text][Text Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)ContainsText` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Find][TextToFind Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), the variable specified in the [Contains Text][ContainsText Property] property is set to `false`. + +### Null or empty Text To Find + +If [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), the variable specified in the [Contains Text][ContainsText Property] property is set to `false`. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[ContainsText Property]: {{< ref "#contains-text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/_index.md new file mode 100644 index 000000000..fc6653945 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Decode Text" +linkTitle: "Decode Text" +description: "Decode text from a specified format (e.g. `\"Base64\"`)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/decode-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/decode-text-block.md new file mode 100644 index 000000000..d96edd44d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/decode-text/decode-text-block.md @@ -0,0 +1,227 @@ +--- +title: "Decode Text" +linkTitle: "Decode Text" +description: "Decodes text from a specified format (e.g. `\"Base64\"`)." +--- + +{{< figure src="/blocks/text-decode-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.DecodeText.DecodeTextBlock)
+ +## Description + +Decodes [Text][Text Property] from the specified [Format][Format Property]. + +## Examples + +### Text decoded from Base64 + +This example will decode the [Base64][] encoded text `"VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw=="` to `"The quick brown fox jumps over the lazy dog"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw=="` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Base64"` | `($)Format` is a variable of type [TextEncodingFormat][] + +#### Result + +Decoding `"VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw=="` with the [Format][Format Property] [Base64] will result in the variable `($)Text` being updated to the following: + +```json +"The quick brown fox jumps over the lazy dog" +``` + +*** + +### Text decoded from Url + +This example will decode the [Url][] encoded text `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"` to `"The quick brown fox jumps over the lazy dog!"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Url"` | `($)Format` is a variable of type [TextEncodingFormat][] + +#### Result + +Decoding `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"` with the [Format][Format Property] [Url] will result in the variable `($)Text` being updated to the following: + +```json +"The quick brown fox jumps over the lazy dog!" +``` + +*** + +### Text decoded from Hex + +This example will decode the [Hex][] encoded text `"54686520717569636B2062726F776E20666F78206A756D7073206F76657220746865206C617A7920646F67"` to `"The quick brown fox jumps over the lazy dog"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"54686520717569636B2062726F776E20666F78206A756D7073206F76657220746865206C617A7920646F67"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Hex"` | `($)Format` is a variable of type [TextEncodingFormat][] + +#### Result + +Decoding `"54686520717569636B2062726F776E20666F78206A756D7073206F76657220746865206C617A7920646F67"` with the [Format][Format Property] [Hex] will result in the variable `($)Text` being updated to the following: + +```json +"The quick brown fox jumps over the lazy dog" +``` + +*** + +### Text decoded from Html + +This example will decode the [Html][] encoded text `"<p>The quick brown fox jumps over the lazy dog!</p>"` to `"The quick brown fox jumps over the lazy dog!
"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"<p>The quick brown fox jumps over the lazy dog!</p>"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Html"` | `($)Format` is a variable of type [TextEncodingFormat][] + +#### Result + +Decoding `"<p>The quick brown fox jumps over the lazy dog!</p>"` with the [Format][Format Property] [Html] will result in the variable `($)Text` being updated to the following: + +```json +"The quick brown fox jumps over the lazy dog!
" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to decode from the specified [Format][Format Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Format + +The [Format][Format Property] used to decode the given [Text][Text Property]. + +[Format][Format Property] can be any of the predefined values: + +* `TextEncodingFormat.Base64` +* `TextEncodingFormat.Url` +* `TextEncodingFormat.Hex` +* `TextEncodingFormat.Html` +* `TextEncodingFormat.Utf8` +* `TextEncodingFormat.Base64Url` + +| | | +|--------------------|---------------------------| +| Data Type | [TextEncodingFormat][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `Base64` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Format][Format Property] is not one of the specified [TextEncodingFormat][] types (e.g. `(TextEncodingFormat)10`). | +| [TextDecodingException][] | Thrown when [Text][Text Property] contains an invalid character for [Base64] decoding. For more information, see [Invalid Base64 Character][InvalidBase64]. | +||Thrown when [Text][Text Property] contains an odd number of characters for [Hex] decoding. For more information, see [Odd number of characters using Hex][InvalidHex]. | +|| Thrown when [Text][Text Property] contains an invalid character for [Base64Url] decoding. For more information, see [Invalid Base64Url Character][InvalidBase64Url]. | + +## Remarks + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to decode, so no operation is performed. + +### Decoding out of range URL characters + +When decoding using the [Url][] [Format][Format Property], characters not in the valid range (i.e.`%00` to `%ff`) will be treated as literal characters (e.g. `"%zzExample%21"` will decode to `"%zzExample!"`). + +### Decoding invalid Hex values + +When decoding using the [Hex] [Format][Format Property], characters not in the valid set (i.e. `0-9` and `A-F`) will overflow (e.g. `G` overflows to `0`), further examples are shown below: +| Encoded Text | Overflows To | Decoded Text | +|--------------|--------------|--------------| +| 4G | 40 | @ | +| 4H | 41 | A | +| 4I | 42 | B | +| J1 | 31 | 1 | +| K1 | 41 | A | +| L1 | 51 | Q | + +### Decoding invalid HTML entities + +When decoding using the [Html] [Format][Format Property], invalid [HTML Entities][HTMLEntity] will be removed (e.g. `"Example&InvalidEntity;"` will decode to `"Example"`). + +### Decoding HTML ampersand + +When decoding using the [Html] [Format][Format Property], any ampersand that is not part of an [HTML Entity][HTMLEntity] will be removed (e.g. `"Example&Something"` will decode to `"ExampleSomething"`). + +### Decoding HTML semicolon + +When decoding using the [Html] [Format][Format Property], any semicolon that is not part of an [HTML Entity][HTMLEntity] will be treated as a literal character (e.g. `"ExampleSomething;"` will decode to `"ExampleSomething;"`). + +### Round-Tripping + +It should be possible to pass the text created by an [Encode Text block][Encode Text] to this block, and then pass the text created by this block back to an [Encode Text block][Encode Text]; this is called round-tripping. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property] decoded from the specified format and reassigns it to the specified [Text][Text Property] property. + +### Known Limitations + +When decoding using the [Html] [Format][Format Property], any HTML5 named [entities][HTMLEntity] (e.g. `"φ"`) will be removed. + +This limitation may be removed in the future. + +[Text Property]: {{< ref "#text" >}} +[Format Property]: {{< ref "#format" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[TextEncodingFormat]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[TextDecodingException]: {{< url path="Cortex.Reference.Exceptions.Text.Encoding.TextDecodingException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Html]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Html" >}} +[Base64]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Base64" >}} +[Hex]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Hex" >}} +[Base64Url]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Base64Url" >}} +[Url]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Url" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[InvalidBase64]: {{< url path="Cortex.Reference.Exceptions.Text.Encoding.TextDecodingException.InvalidBase64" >}} +[InvalidHex]: {{< url path="Cortex.Reference.Exceptions.Text.Encoding.TextDecodingException.InvalidHex" >}} +[InvalidBase64Url]: {{< url path="Cortex.Reference.Exceptions.Text.Encoding.TextDecodingException.InvalidBase64Url" >}} + +[Encode Text]: {{< url path="Cortex.Reference.Blocks.Text.EncodeText.EncodeText.MainDoc" >}} +[HTMLEntity]: {{< url path="Cortex.Reference.Glossary.F-J.HTMLEntity" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/_index.md new file mode 100644 index 000000000..38ce0b2f7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Encode Text" +linkTitle: "Encode Text" +description: "Encode text to a specified format (e.g. `\"Base64\"`)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/encode-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/encode-text-block.md new file mode 100644 index 000000000..21b94e1f9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/encode-text/encode-text-block.md @@ -0,0 +1,177 @@ +--- +title: "Encode Text" +linkTitle: "Encode Text" +description: "Encodes text to a specified format (e.g. `\"Base64\"`)." +--- + +{{< figure src="/blocks/text-encode-text-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.EncodeText.EncodeTextBlock)
+ +## Description + +Encodes [Text][Text Property] to a specified [Format][Format Property]. + +## Examples + +### Text encoded to Base64 + +This example will encode the text `"The quick brown fox jumps over the lazy dog"` to `"VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw=="`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Base64"` | `($)Format` is a variable of type [TextEncodingFormat][] | + +#### Result + +Encoding `"The quick brown fox jumps over the lazy dog"` to the [Format][Format Property] [Base64][] will result in the variable `($)Text` being updated to the following: + +```json +"VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw==" +``` + +*** + +### Text encoded to Url + +This example will encode the text `"The quick brown fox jumps over the lazy dog!"` to `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Url"` | `($)Format` is a variable of type [TextEncodingFormat][] + +#### Result + +Encoding `"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21"` to the [Format][Format Property] [Url] will result in the variable `($)Text` being updated to the following: + +```json +"The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog%21" +``` + +*** + +### Text encoded to Hex + +This example will encode the text `"The quick brown fox jumps over the lazy dog"` to `"54686520717569636b2062726f776e20666f78206a756d7073206f76657220746865206c617a7920646f67"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Hex"` | `($)Format` is a variable of type [TextEncodingFormat][] | + +#### Result + +Encoding `"The quick brown fox jumps over the lazy dog"` to the [Format][Format Property] [Hex][] will result in the variable `($)Text` being updated to the following: + +```json +"54686520717569636b2062726f776e20666f78206a756d7073206f76657220746865206c617a7920646f67" +``` + +*** + +### Text encoded to Html + +This example will encode the text `"The quick brown fox jumps over the lazy dog!
"` to `"<p>The quick brown fox jumps over the lazy dog!</p>"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog!
"` | `($)Text` is a variable of type [String][] | +| [Format][Format Property] | `($)Format`, with value `"TextEncodingFormat.Html"` | `($)Format` is a variable of type [TextEncodingFormat][] | + +#### Result + +Encoding `"The quick brown fox jumps over the lazy dog!
"` to the [Format][Format Property] [Html][] will result in the variable `($)Text` being updated to the following: + +```json +"<p>The quick brown fox jumps over the lazy dog!</p>" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to encode to the specified [Format][Format Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Format + +The [Format][Format Property] used to encode the given [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TextEncodingFormat][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `Base64` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when the format is not one of the specified [Format][Format Property] types (e.g. `(TextEncodingFormat)10`). | + +## Remarks + +### Encoding to Base64 + +When encoding to [Base64][] a new line character is added every 76 characters. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), no operation is performed. + +### Round-Tripping + +It should be possible to pass the text created by a [Decode Text][] block to this block, and then pass the text created by this block back to an [Decode Text][] block; this is called round-tripping. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Text][Text Property], encodes to [Format][Format Property] and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[Format Property]: {{< ref "#format" >}} +[Decode Text]: {{< url path="Cortex.Reference.Blocks.Text.DecodeText.DecodeText.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[TextEncodingFormat]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.MainDoc" >}} +[Html]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Html" >}} +[Base64]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Base64" >}} +[Hex]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Hex" >}} +[Base64Url]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Base64Url" >}} +[Url]: {{< url path="Cortex.Reference.DataTypes.Text.Encoding.TextEncodingFormat.Url" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/_index.md new file mode 100644 index 000000000..f11296cc6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Find And Remove Text" +linkTitle: "Find And Remove Text" +description: "Find text in another text, and remove it." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md new file mode 100644 index 000000000..0655ed4d0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md @@ -0,0 +1,249 @@ +--- +title: "Find And Remove All Text" +linkTitle: "Find And Remove All Text" +description: "Finds and removes all occurrences of text from a given text." +--- + +{{< figure src="/blocks/text-find-and-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FindAndRemoveText.FindAndRemoveAllTextBlock)
+ +## Description + +Finds and removes all occurrences of [Text To Remove][TextToRemove Property] from a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Remove][TextToRemove Property]. + +## Examples + +### Remove all occurrences of Text To Remove (Ordinal) + +This example will find and remove all occurrences of `"The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"The"` | `($)TextToRemove` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over the lazy dog" +``` + +*** + +### Remove all occurrences of Text To Remove (Ordinal Ignore Case) + +This example will find and remove all occurrences of `"The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"The"` | `($)TextToRemove` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over lazy dog" +``` + +*** + +### Remove all occurrences that match the pattern in Text To Remove + +This example will find and remove all occurrences of text that match the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"?he"` | `($)TextToRemove` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` and `"the"` that matches the pattern `"?he"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over lazy dog" +``` + +*** + +### Remove all occurrences that match the regex in Text To Remove + +This example will find and remove all occurrences of text that match the regex `"^The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"^The"` | `($)TextToRemove` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` at the start of the sentence that matches the regex `"^The"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over the lazy dog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and remove all occurrences of [Text To Remove][TextToRemove Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Remove + +The [Text To Remove][TextToRemove Property] all occurrences of, from [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Remove][TextToRemove Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Remove][TextToRemove Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Remove][TextToRemove Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Remove][TextToRemove Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to remove from, so no operation is performed. + +### Null or empty Text To Remove + +If [Text To Remove][TextToRemove Property] is `null` or empty (i.e. `""`) there is nothing to remove, so no operation is performed. + +### Text To Remove is not present + +If [Text To Remove][TextToRemove Property] is not present there is nothing to remove, so no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] with all occurrences of [Text To Remove][TextToRemove Property] removed and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToRemove Property]: {{< ref "#text-to-remove" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md new file mode 100644 index 000000000..e32e6504e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md @@ -0,0 +1,282 @@ +--- +title: "Find And Remove Text" +linkTitle: "Find And Remove Text" +description: "Finds and removes the specified occurrence of text from a given text." +--- + +{{< figure src="/blocks/text-find-and-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FindAndRemoveText.FindAndRemoveTextBlock)
+ +## Description + +Finds and removes the specified [Occurrence][Occurrence Property] of [Text To Remove][TextToRemove Property] from a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Remove][TextToRemove Property]. + +## Examples + +### Remove the first Occurrence of Text To Remove (Ordinal) + +This example will find and remove the first occurrence of `"The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"The"` | `($)TextToRemove` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means find and remove the first occurrence; `2` means second etc. + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over the lazy dog" +``` + +*** + +### Remove the last Occurrence of Text To Remove (Ordinal Ignore Case) + +This example will find and remove the last occurrence of `"The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"The"` | `($)TextToRemove` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means find and remove the last occurrence; `-2` means second last etc. + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second and last occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"The quick brown fox jumps over lazy dog" +``` + +*** + +### Remove the first Occurrence matching the pattern in Text To Remove + +This example will find and remove the first occurrence of text matching the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"?he"` | `($)TextToRemove` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means find and remove the first occurrence; `2` means second etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the pattern `"?he"`; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +" quick brown fox jumps over the lazy dog" +``` + +*** + +### Remove the last Occurrence matching the regex in Text To Remove + +This example will find and remove the last occurrence of text matching the regex `"(fox|dog)"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Remove][TextToRemove Property] | `($)TextToRemove`, with value `"(fox\|dog)"` | `($)TextToRemove` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means find and remove the last occurrence; `-2` means second last etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the regex `"(fox|dog)"`; the first occurrence is `"fox"` and the second and last occurrence is `"dog"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"The quick brown fox jumps over the lazy " +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and remove the specified [Occurrence][Occurrence Property] of [Text To Remove][TextToRemove Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Remove + +The [Text To Remove][TextToRemove Property] the specified [Occurrence][Occurrence Property] of, from [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Occurrence + +The [Occurrence][Occurrence Property] of [Text To Remove][TextToRemove Property] from [Text][Text Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Remove][TextToRemove Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Remove][TextToRemove Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Remove][TextToRemove Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Remove][TextToRemove Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Occurrences + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to remove from, so no operation is performed. + +### Null or empty Text To Remove + +If [Text To Remove][TextToRemove Property] is `null` or empty (i.e. `""`) there is nothing to remove, so no operation is performed. + +### Text To Remove or Occurrence is not present + +If [Text To Remove][TextToRemove Property] or the specified [Occurrence][Occurrence Property] is not present, there is nothing to remove, so no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] with the specified [Occurrence][Occurrence property] of [Text To Remove][TextToRemove Property] removed and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToRemove Property]: {{< ref "#text-to-remove" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/_index.md new file mode 100644 index 000000000..f9038379b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Find And Replace Text" +linkTitle: "Find And Replace Text" +description: "Find text in another text, and replace it." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md new file mode 100644 index 000000000..f1cd97e76 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md @@ -0,0 +1,270 @@ +--- +title: "Find And Replace All Text" +linkTitle: "Find And Replace All Text" +description: "Finds and replaces all occurrences of text in a given text." +--- + +{{< figure src="/blocks/text-find-and-replace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FindAndReplaceText.FindAndReplaceAllTextBlock)
+ +## Description + +Finds and replaces all occurrences of [Text To Replace][TextToReplace Property] with the specified [Replacement Text][ReplacementText Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Replace][TextToReplace Property]. + +## Examples + +### Replace all occurrences of Text To Replace (Ordinal) + +This example will find and replace all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"The"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over the lazy dog" +``` + +*** + +### Replace all occurrences of Text To Replace (Ordinal Ignore Case) + +This example will find and replace all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"The"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over a lazy dog" +``` + +*** + +### Replace all occurrences that match the pattern in Text To Replace + +This example will find and replace all occurrences of text that match the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"?he"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` and `"the"` that matches the pattern `"?he"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over a lazy dog" +``` + +*** + +### Replace all occurrences that match the regex in Text To Replace + +This example will find and replace all occurrences of text that match the regex `"^The"` from `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"^The"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` at the start of the sentence that matches the regex `"^The"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over the lazy dog" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and replace all occurrences of [Text To Replace][TextToReplace Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Replace + +The [Text To Replace][TextToReplace Property] all occurrences with [Replacement Text][ReplacementText Property] in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Replacement Text + +The [Replacement Text][ReplacementText Property] used to replace all occurrences of [Text To Replace][TextToReplace Property] in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Replace][TextToReplace Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Replace][TextToReplace Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Replace][TextToReplace Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Replace][TextToReplace Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to replace in, so no operation is performed. + +### Null or empty Text To Replace + +If [Text To Replace][TextToReplace Property] is `null` or empty (i.e. `""`) there is nothing to replace, so no operation is performed. + +### Null or empty Replacement Text + +If [Replacement Text][ReplacementText Property] is `null` or empty (i.e. `""`) all occurrences of [Text To Replace][TextToReplace Property] are replaced with an empty text (i.e. `""`). + +### Text To Replace is not present + +If [Text To Replace][TextToReplace Property] is not present there is nothing to replace, so no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] with all occurrences of [Text To Replace][TextToReplace Property] replaced and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToReplace Property]: {{< ref "#text-to-replace" >}} +[ReplacementText Property]: {{< ref "#replacement-text" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md new file mode 100644 index 000000000..d9f559362 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md @@ -0,0 +1,303 @@ +--- +title: "Find And Replace Text" +linkTitle: "Find And Replace Text" +description: "Finds and replaces the specified occurrence of text in a given text." +--- + +{{< figure src="/blocks/text-find-and-replace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FindAndReplaceText.FindAndReplaceTextBlock)
+ +## Description + +Finds and replaces the specified [Occurrence][Occurrence Property] of [Text To Replace][TextToReplace Property] with the specified [Replacement Text][ReplacementText Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the [Text To Replace][TextToReplace Property]. + +## Examples + +### Replace the first Occurrence of Text To Replace (Ordinal) + +This example will find and replace the first occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"The"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means find and replace the first occurrence; `2` means second etc. + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over the lazy dog" +``` + +*** + +### Replace the last occurrence of Text To Replace (Ordinal Ignore Case) + +This example will find and replace the last occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"The"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means find and replace the last occurrence; `-2` means second last etc. + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second and last occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"The quick brown fox jumps over a lazy dog" +``` + +*** + +### Replace the first Occurrence matching the pattern in Text To Replace + +This example will find and replace the first occurrence of text matching the pattern `"?he"` from `"The quick brown fox jumps over the lazy dog"` with `"a"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"?he"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"a"` | `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `1` means find and replace the first occurrence; `2` means second etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the pattern `"?he"`; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"a quick brown fox jumps over the lazy dog" +``` + +*** + +### Replace the last Occurrence matching the regex in Text To Replace + +This example will find and replace the last occurrence of text matching the regex `"(fox|dog)"` from `"The quick brown fox jumps over the lazy dog"` with `"cat"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Replace][TextToReplace Property] | `($)TextToReplace`, with value `"(fox\|dog)"` | `($)TextToReplace` is a variable of type [String][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText`, with value `"cat"` | `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Result + +An [Occurrence][Occurrence Property] of `-1`, means find and replace the last occurrence; `-2` means second last etc. + +`"The quick brown fox jumps over the lazy dog"` contains two occurrences that match the regex `"(fox|dog)"`; the first occurrence is `"fox"` and the second and last occurrence is `"dog"`. Therefore, the variable `($)Text` will be updated to the following: + +```json +"The quick brown fox jumps over the lazy cat" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and replace the specified [Occurrence][Occurrence Property] of [Text To Replace][TextToReplace Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Replace + +The [Text To Replace][TextToReplace Property] the specified [Occurrence][Occurrence Property] with [Replacement Text][ReplacementText Property] in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Replacement Text + +The [Replacement Text][ReplacementText Property] used to replace the specified [Occurrence][Occurrence Property] of [Text To Replace][TextToReplace Property] in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Occurrence + +The [Occurrence][Occurrence Property] of [Text To Replace][TextToReplace Property] in [Text][Text Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Replace][TextToReplace Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Replace][TextToReplace Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Replace][TextToReplace Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when [Search Options][SearchOptions Property] is either `SearchOptions.Regex` or `SearchOptions.PatternMatching` and the execution time of the search exceeds `30` seconds. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [Text To Replace][TextToReplace Property] is not a valid regex (e.g. `(`). | + +## Remarks + +### Occurrences + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to replace in, so no operation is performed. + +### Null or empty Text To Replace + +If [Text To Replace][TextToReplace Property] is `null` or empty (i.e. `""`) there is nothing to replace, so no operation is performed. + +### Null or empty Replacement Text + +If [Replacement Text][ReplacementText Property] is `null` or empty (i.e. `""`) the specified [Occurrence][Occurrence Property] of [Text To Replace][TextToReplace Property] is replaced with an empty text (i.e. `""`). + +### Text To Replace or Occurrence is not present + +If [Text To Replace][TextToReplace Property] or the specified [Occurrence][Occurrence Property] is not present there is nothing to replace, so no operation is performed. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] with the specified [Occurrence][Occurrence property] of [Text To Replace][TextToReplace Property] replaced and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Text Property]: {{< ref "#text" >}} +[TextToReplace Property]: {{< ref "#text-to-replace" >}} +[ReplacementText Property]: {{< ref "#replacement-text" >}} +[Occurrence Property]: {{< ref "#occurrence" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/format-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/_index.md new file mode 100644 index 000000000..3510eb0bb --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Format Text" +linkTitle: "Format Text" +description: "Format text containing format parameters (i.e. {0}) by replacing them with other values." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-value-block-1.md b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-value-block-1.md new file mode 100644 index 000000000..4b5974851 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-value-block-1.md @@ -0,0 +1,186 @@ +--- +title: "Format Text With Value" +linkTitle: "Format Text With Value" +description: "Formats text by replacing all `{0}` format parameters in a specified format template with a given value." +--- + +{{< figure src="/blocks/text-format-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FormatText.FormatTextWithValueBlock`1)
+ +## Description + +Replaces all `{0}` format parameters in the specified [Format Template][FormatTemplate Property] with the given [Value][Value Property], saving the result as [Text][Text Property]. + +An additional [Format Provider][FormatProvider Property] option can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting). + +## Examples + +### Text Value + +This example will format `"Hello {0}"` with `"world!"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"Hello {0}"` | `($)FormatTemplate` is a variable of type [String][] | +| [Value][Value Property] | `($)Value`, with value `"world!"` | `($)Value` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `null` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Formatting `"Hello {0}"` with `"world!"` results in the variable `($)Text` being updated to the following: + +```json +"Hello world!" +``` + +*** + +### Double Value using American English ("en-US") + +This example will format `"Your final bill is {0:C2}"` with `99.99`. + +The format parameter `{0:C2}` will display the double value as U.S currency to two decimal places (i.e. `$99.99`): + +* `0` - is replaced by the double value. +* `C` - indicates to include the currency symbol for the specified culture (i.e. `$`). +* `2` - indicates the number of decimal places to format the double value to. + +For information about format templates and parameters, please see [Text Formatting][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"Your final bill is {0:C2}"` | `($)FormatTemplate` is a variable of type [String][] | +| [Value][Value Property] | `($)Value`, with value `99.99` | `($)Value` is a variable of type [Double][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Formatting `"Your final bill is {0:C2}"` with `99.99` results in the variable `($)Text` being updated to the following: + +```json +"Your final bill is $99.99" +``` + +*** + +## Properties + +### Format Template + +[Format Template][FormatTemplate Property] can be specified to define the format of the resultant [Text][Text Property]. + +All `{0}` format parameters in [Format Template][FormatTemplate Property] will be replaced with [Value][Value Property]. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), or does not contain any `{0}` format parameters, nothing is replaced; [Text][Text Property] will be set to the value of [Format Template][FormatTemplate Property]. + +For information about format templates and parameters, please see [Text Formatting][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `@"{0}"` | + +### Value + +The [Value][Value Property] to replace all `{0}` format parameters with. + +[Value][Value Property] does not have to be text, it can be any data type. Any non-text value will be converted to its text representation when it is replaced. + +For information about how types are converted to their text representation please see [Converting Objects To Text][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TValue][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Format Provider + +[Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting.). + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IFormatProvider][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +### Text + +The formatted [Text][Text Property] that results from replacing all `{0}` format parameters in [Format Template][FormatTemplate Property] with [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [FormatException][] | Thrown when [Format Template][FormatTemplate Property] contains a format parameter not equal to zero (e.g. `"Hello {1}"`). | +| | Thrown when [Format Template][FormatTemplate Property] contains a format parameter that is invalid or not well-formed (e.g. `"Cost is {0:Q2}`, as `"Q"` is not a [valid format parameter][]). | + +## Remarks + +### Text Formatting + +Please note that changes to operating system settings, could result in some of the examples above displaying different results. + +For information about format templates and parameters, please see [Text Formatting][]. + +### Null or Empty Format Template + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), or does not contain any `{0}` format parameters, nothing is replaced; [Text][Text Property] will be set to the value of [Format Template][FormatTemplate Property]. + +### Null Format Provider + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +[FormatTemplate Property]: {{< ref "#format-template" >}} +[Value Property]: {{< ref "#value" >}} +[FormatProvider Property]: {{< ref "#format-provider" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[FormatException]: {{< url path="MSDocs.DotNet.Api.System.FormatException" >}} + +[Converting Objects To Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.ConvertingObjectsToText.MainDoc" >}} +[Invariant Culture rules]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.InvariantCulture.MainDoc" >}} +[Text Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.MainDoc" >}} +[Valid Format Parameter]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatTemplates" >}} + +[TValue]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} +[IFormatProvider]: {{< url path="Cortex.Reference.DataTypes.Text.IFormatProvider.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-values-block-1.md b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-values-block-1.md new file mode 100644 index 000000000..25aa73ddd --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/format-text/format-text-with-values-block-1.md @@ -0,0 +1,209 @@ +--- +title: "Format Text With Values" +linkTitle: "Format Text With Values" +description: "Formats text by replacing all format parameters (e.g. `{0}` or `{1}` or `{2}`) in a specified format template with given values." +--- + +{{< figure src="/blocks/text-format-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.FormatText.FormatTextWithValuesBlock`1)
+ +## Description + +Replaces all format parameters (e.g. `{0}` or `{1}` or `{2}`) in the given [Format Template][FormatTemplate Property] with the specified [Values][Values Property], saving the result as [Text][Text Property]. + +An additional [Format Provider][FormatProvider Property] option can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting). + +## Examples + +### Text Values + +This example will format `"Hello {0} {1}"` with `["Mr", "Smith"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"Hello {0} {1}"` | `($)FormatTemplate` is a variable of type [String][] | +| [Values][Values Property] | `($)Values`, with value `["Mr", "Smith"]` | `($)Values` is a variable of type [IEnumerable][]<[String][]> | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `null` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Formatting `"Hello {0} {1}"` with `["Mr", "Smith"]` results in the variable `($)Text` being updated to the following: + +```json +"Hello Mr Smith" +``` + +*** + +### Multiple non-text values using American English ("en-US") + +This example will format `"Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding."` with `[99.99, 0.8, 40]`. + +The format parameter `{0:C2}` will display the `99.99` as U.S currency to two decimal places (i.e. `$99.99`): + +* `0` - is replaced by the double value `99.99`. +* `C` - indicates to include the currency symbol for the specified culture (i.e. `$`). +* `2` - indicates to format the double value to two decimal places. + +The format parameter `{1:P0}` will display the `0.8` as a percentage to zero decimal places (i.e. `80 %`): + +* `1` - is replaced by the double value `0.8`. +* `P` - indicates the value should be formatted as a percentage. +* `0` - indicates to format the percentage value to zero decimal places. + +The format parameter `{2:C2}` will display the `40` as U.S currency to two decimal places (i.e. `$40.00`): + +* `2` - is replaced by the double value `40`. +* `C` - indicates to include the currency symbol for the specified culture (i.e. `$`). +* `2` - indicates to format the double value to two decimal places. + +For information about format templates and parameters, please see [Text Formatting][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding."` | `($)FormatTemplate` is a variable of type [String][] | +| [Values][Values Property] | `($)Values`, with value `[99.99, 0.8, 40]` | `($)Values` is a variable of type [IEnumerable][]<[Double][]> | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +`"Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding."` with `[99.99, 0.8, 40]` results in the variable `($)Text` being updated to the following: + +```json +"Your latest payment of $99.99 has been received. You have paid 80 % of your total and have $40.00 outstanding." +``` + +*** + +## Properties + +### Format Template + +[Format Template][FormatTemplate Property] can be specified to define the format of the resultant [Text][Text Property]. + +All format parameters (e.g. `{0}` or `{1}` or `{2}`) in [Format Template][FormatTemplate Property] will be replaced with the corresponding value in [Values][Values Property]. Format parameter `{0}` will be replaced with the first value in [Values][Values Property]; `{1}` will be replaced with the second value in [Values][Values Property] etc. + +The number of unique format parameters must be equal to or less than the number of items in [Values][Values Property]. + +The index of each format parameter must be equal to or less than the number of items in [Values][Values Property] - `1`. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), or does not contain any format parameters, nothing is replaced; [Text][Text Property] will be set to the value of [Format Template][FormatTemplate Property]. + +For information about format templates and parameters, please see [Text Formatting][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `@"{0} {1}"` | + +### Values + +The [Values][Values Property] to replace all format parameters with. + +If a value does not have a corresponding format parameter, it is ignored. + +[Values][Values Property] does not have to contain all text values, it can contain any data types. Any non-text values will be converted to their text representation when they are replaced. + +If any value is `null` or empty (i.e. `""`), an empty text (i.e. `""`) will replace the corresponding format parameter. + +For information about how types are converted to their text representation please see [Converting Objects To Text][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TValue][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `new List(Cortex.Blocks.Text.GetText.GetTextAtBeginningBlock)
+ +## Description + +Gets a [Length][Length Property] of [text][TextAtBeginning Property] from the beginning of a given [Text][Text Property]. + +## Examples + +### Get a Length of text from the beginning of a given Text + +This example will get the first `3` characters from the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | +| [Text At Beginning][TextAtBeginning Property] | `($)TextAtBeginning`, with no value | `($)TextAtBeginning` is a variable that will be set to a [String][] | + +#### Result + +Getting the first `3` characters from the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)TextAtBeginning` being updated to the following: + +```json +"ABC" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Text At Beginning][TextAtBeginning Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Length + +The [Length][Length Property] of text to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Text At Beginning + +The [Length][Length Property] of text at the beginning of [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextAtBeginning` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Length][Length Property] is greater than the length of [Text][Text Property]. | + +## Remarks + +### Negative Length + +If [Length][Length Property] is negative, the variable specified in the [Text At Beginning][TextAtBeginning Property] property will be set to the value of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, the variable specified in the [Text At Beginning][TextAtBeginning Property] property will be set to empty (i.e. `""`). + +[Text Property]: {{< ref "#text" >}} +[Length Property]: {{< ref "#length" >}} +[TextAtBeginning Property]: {{< ref "#text-at-beginning" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-end-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-end-block.md new file mode 100644 index 000000000..61d54d6ce --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-end-block.md @@ -0,0 +1,114 @@ +--- +title: "Get Text At End" +linkTitle: "Get Text At End" +description: "Gets a length of text from the end of a given text." +--- + +{{< figure src="/blocks/text-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetText.GetTextAtEndBlock)
+ +## Description + +Gets a [Length][Length Property] of [text][TextAtEnd Property] from the end of a given [Text][Text Property]. + +## Examples + +### Get a Length of text from the end of a given Text + +This example will get the last `3` characters from the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | +| [Text At End][TextAtEnd Property] | `($)TextAtEnd`, with no value | `($)TextAtEnd` is a variable that will be set to a [String][] | + +#### Result + +Getting the last `3` characters from the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)TextAtEnd` being updated to the following: + +```json +"XYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Text At End][TextAtEnd Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Length + +The [Length][Length Property] of text to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Text At End + +The [Length][Length Property] of text at the end of [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextAtEnd` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Length][Length Property] is greater than the length of [Text][Text Property]. | + +## Remarks + +### Negative Length + +If [Length][Length Property] is negative, the variable specified in the [Text At End][TextAtEnd Property] property will be set to the value of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, the variable specified in the [Text At End][TextAtEnd Property] property will be set to empty (i.e. `""`). + +[Text Property]: {{< ref "#text" >}} +[Length Property]: {{< ref "#length" >}} +[TextAtEnd Property]: {{< ref "#text-at-end" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-index-block.md new file mode 100644 index 000000000..1bd70496f --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-at-index-block.md @@ -0,0 +1,136 @@ +--- +title: "Get Text At Index" +linkTitle: "Get Text At Index" +description: "Gets a length of text at the specified index of a given text." +--- + +{{< figure src="/blocks/text-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetText.GetTextAtIndexBlock)
+ +## Description + +Gets a [Length][Length Property] of [text][TextAtIndex Property] at the specified [Index][Index Property] of a given [Text][Text Property]. + +## Examples + +### Get a Length of text at the specified Index of a given Text + +This example will get `3` characters at index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `3` | `($)Index` is a variable of type [Int32][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | +| [Text At Index][TextAtIndex Property] | `($)TextAtIndex`, with no value | `($)TextAtIndex` is a variable that will be set to a [String][] | + +#### Result + +`"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, getting `3` characters at (and including) index `3` results in the variable `($)TextAtIndex` being updated to the following: + +```json +"DEF" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Text At Index][TextAtIndex Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Index + +The [Index][Index Property] to get the text from. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Length + +The [Length][Length Property] of text to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Text At Index + +The [Length][Length Property] of text at the [Index][Index Property] of [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextAtIndex` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property]is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | +| | Thrown when [Index][Index Property] + a positive [Length][Length Property] is greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Negative Length + +A negative [Length][Length Property] can be used to get all text at and after the [Index][Index Property] of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, the variable specified in the [Text At Index][TextAtIndex Property] property will be set to empty (i.e. `""`). + +### Index is inclusive + +The [Index][Index Property] property is an inclusive [index][Indexes], which means the character at the index will be included in the retrieved [text][TextAtIndex Property]. + +[Text Property]: {{< ref "#text" >}} +[Index Property]: {{< ref "#index" >}} +[Length Property]: {{< ref "#length" >}} +[TextAtIndex Property]: {{< ref "#text-at-index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-before-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-before-index-block.md new file mode 100644 index 000000000..f02d30197 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-before-index-block.md @@ -0,0 +1,136 @@ +--- +title: "Get Text Before Index" +linkTitle: "Get Text Before Index" +description: "Gets a length of text before the specified index of a given text." +--- + +{{< figure src="/blocks/text-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetText.GetTextBeforeIndexBlock)
+ +## Description + +Gets a [Length][Length Property] of [text][TextBeforeIndex Property] before the specified [Index][Index Property] of a given [Text][Text Property]. + +## Examples + +### Get a Length of text before the specified Index of a given Text + +This example will get `3` characters before index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `3` | `($)Index` is a variable of type [Int32][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | +| [Text Before Index][TextBeforeIndex Property] | `($)TextBeforeIndex`, with no value | `($)TextBeforeIndex` is a variable that will be set to a [String][] | + +#### Result + +`"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, getting `3` characters before index `3` results in the variable `($)TextBeforeIndex` being updated to the following: + +```json +"ABC" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Text Before Index][TextBeforeIndex Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Index + +The [Index][Index Property] to get the text before. This is an exclusive index, which means the character at the specified index won't be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Length + +The [Length][Length Property] of text to get. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +### Text Before Index + +The [Length][Length Property] of text before the [Index][Index Property] of [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextBeforeIndex` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than `1` or greater than the length of [Text][Text Property] - `1`. | +| | Thrown when [Index][Index Property] - a positive [Length][Length Property] is less than `1`. | + +## Remarks + +### Negative Length + +A negative [Length][Length Property] can be used to get all text before the [Index][Index Property] of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, the variable specified in the [Text Before Index][TextBeforeIndex Property] property will be set to empty (i.e. `""`). + +### Index is exclusive + +The [Index][Index Property] property is an exclusive [index][Indexes], which means the character at the index will not be included in the retrieved [text][TextBeforeIndex Property]. + +[Text Property]: {{< ref "#text" >}} +[Index Property]: {{< ref "#index" >}} +[Length Property]: {{< ref "#length" >}} +[TextBeforeIndex Property]: {{< ref "#text-before-index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-between-indexes-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-between-indexes-block.md new file mode 100644 index 000000000..d047c36a7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/get-text/get-text-between-indexes-block.md @@ -0,0 +1,164 @@ +--- +title: "Get Text Between Indexes" +linkTitle: "Get Text Between Indexes" +description: "Gets text between the specified start index and end index of a given text." +--- + +{{< figure src="/blocks/text-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.GetText.GetTextBetweenIndexesBlock)
+ +## Description + +Gets [text][TextBetweenIndexes Property] between the specified [Start Index][StartIndex Property] and [End Index][EndIndex Property] of a given [Text][Text Property]. + +## Examples + +### Get text between the specified Start Index and End Index of a given Text + +This example will get all characters between start index `0` and end index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `0` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `3` | `($)EndIndex` is a variable of type [Int32][] | +| [Text Between Indexes][TextBetweenIndexes Property] | `($)TextBetweenIndexes`, with no value | `($)TextBetweenIndexes` is a variable that will be set to a [String][] | + +#### Result + +`"A"` is at index `0` and `"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, getting all characters between (and including) start index `0` and end index `3` results in the variable `($)TextBetweenIndexes` being updated to the following: + +```json +"ABCD" +``` + +*** + +### Get text where Start Index is greater than End Index + +This example will get all characters between start index `3` and end index `0` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `3` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `0` | `($)EndIndex` is a variable of type [Int32][] | +| [Text Between Indexes][TextBetweenIndexes Property] | `($)TextBetweenIndexes`, with no value | `($)TextBetweenIndexes` is a variable that will be set to a [String][] | + +#### Result + +In this example the start index `3` is greater than the end index `0`. When this occurs, the block simply swaps the indexes before it processes the text. + +Therefore, having start index `3` and end index `0` is the same as having start index `0` and end index `3`. + +`"A"` is at index `0` and `"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +Therefore, getting all characters between (and including) start index `3` and end index `0`, or start index `0` and end index `3`, results in the variable `($)TextBetweenIndexes` being updated to the following: + +```json +"ABCD" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to get the [Text Between Indexes][TextBetweenIndexes Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Start Index + +The [Start Index][StartIndex Property] used to get the text. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### End Index + +The [End Index][EndIndex Property] used to get the text. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Text Between Indexes + +The text between (and including) the [Start Index][StartIndex Property] and [End Index][EndIndex Property] of [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextBetweenIndexes` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Start Index][StartIndex Property] or [End Index][EndIndex Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Start Index and End Index are inclusive + +The [Start Index][StartIndex Property] and [End Index][EndIndex Property] properties are both inclusive [indexes][], which means the characters at those indexes will be included in the retrieved [text][TextBetweenIndexes Property]. + +### Start Index greater than End Index + +[Start Index][StartIndex Property] can be greater than [End Index][EndIndex Property]. If this is the case, the values of the indexes will be swapped. See [Example][StartIndexGreaterThanEndIndex Example] above. + +[Text Property]: {{< ref "#text" >}} +[StartIndex Property]: {{< ref "#start-index" >}} +[EndIndex Property]: {{< ref "#end-index" >}} +[TextBetweenIndexes Property]: {{< ref "#text-between-indexes" >}} + +[StartIndexGreaterThanEndIndex Example]: {{< ref "#get-text-where-start-index-is-greater-than-end-index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/_index.md new file mode 100644 index 000000000..1b1f9d50d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Is Text" +linkTitle: "Is Text" +description: "Check if text is equal to another text, `null`, empty (i.e. `\"\"`), or whitespace (e.g. `\" \"`)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-block.md new file mode 100644 index 000000000..3fad2c560 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-block.md @@ -0,0 +1,165 @@ +--- +title: "Is Text Empty" +linkTitle: "Is Text Empty" +description: "Checks if text is empty (i.e. `\"\"`)." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextEmptyBlock)
+ +## Description + +Checks if [Text][Text Property] is empty (i.e. `""`) . + +For information about empty, please see [Empty Text and Whitespace][]. + +## Examples + +### Text is empty + +This example will check if `""` is empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `""` | `($)Text` is a variable of type [String][] | +| [Text Is Empty][TextIsEmpty Property] | `($)TextIsEmpty`, with no value | `($)TextIsEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`""` is empty (i.e. `""`), resulting in the variable `($)TextIsEmpty` being updated to the following: + +```json +true +``` + +*** + +### Text is null + +This example will check if `null` is empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` | `($)Text` is a variable of type [String][] | +| [Text Is Empty][TextIsEmpty Property] | `($)TextIsEmpty`, with no value | `($)TextIsEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`null` is not empty (i.e. `""`), resulting in the variable `($)TextIsEmpty` being updated to the following: + +```json +false +``` + +*** + +### Text is whitespace + +This example will check if `" "` is empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" "` | `($)Text` is a variable of type [String][] | +| [Text Is Empty][TextIsEmpty Property] | `($)TextIsEmpty`, with no value | `($)TextIsEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`" "` is not empty (i.e. `""`), resulting in the variable `($)TextIsEmpty` being updated to the following: + +```json +false +``` + +*** + +### Text is not empty + +This example will check if `"The quick brown fox jumps over the lazy dog"` is empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text Is Empty][TextIsEmpty Property] | `($)TextIsEmpty`, with no value | `($)TextIsEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not empty (i.e. `""`), resulting in the variable `($)TextIsEmpty` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is empty (i.e. `""`). + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text Is Empty + +The result of the is empty check. + +If the [Text][Text Property] is empty (i.e. `""`), the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsEmpty` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null Text + +If [Text][Text Property] is `null` the variable specified in the [Text Is Empty][TextIsEmpty Property] property will be set to `false`. See [Example][NullText Example] above. + +### Whitespace Text + +If [Text][Text Property] is whitespace (e.g. `" "`) the variable specified in the [Text Is Empty][TextIsEmpty Property] property will be set to `false`. See [Example][WhitespaceText Example] above. + +[Text Property]: {{< ref "#text" >}} +[TextIsEmpty Property]: {{< ref "#text-is-empty-1" >}} + +[NullText Example]: {{< ref "#text-is-null" >}} +[WhitespaceText Example]: {{< ref "#text-is-whitespace" >}} + +[Empty Text and Whitespace]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.EmptyTextAndWhitespace.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-or-whitespace-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-or-whitespace-block.md new file mode 100644 index 000000000..b1c5b89e7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-empty-or-whitespace-block.md @@ -0,0 +1,160 @@ +--- +title: "Is Text Empty Or Whitespace" +linkTitle: "Is Text Empty Or Whitespace" +description: "Checks if text is empty (i.e. `\"\"`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters)." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextEmptyOrWhitespaceBlock)
+ +## Description + +Checks if [Text][Text Property] is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +For information about empty and whitespace, please see [Empty Text and Whitespace][]. + +## Examples + +### Text is empty + +This example will check if `""` is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `""` | `($)Text` is a variable of type [String][] | +| [Text Is Empty Or Whitespace][TextIsEmptyOrWhitespace Property] | `($)TextIsEmptyOrWhitespace`, with no value | `($)TextIsEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`""` is empty (i.e. `""`), resulting in the variable `($)TextIsEmptyOrWhitespace` being updated to the following: + +```json +true +``` + +*** + +### Text is whitespace + +This example will check if `" "` is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" "` | `($)Text` is a variable of type [String][] | +| [Text Is Empty Or Whitespace][TextIsEmptyOrWhitespace Property] | `($)TextIsEmptyOrWhitespace`, with no value | `($)TextIsEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`" "` is whitespace, resulting in the variable `($)TextIsEmptyOrWhitespace` being updated to the following: + +```json +true +``` + +*** + +### Text is null + +This example will check if `null` is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` | `($)Text` is a variable of type [String][] | +| [Text Is Empty Or Whitespace][TextIsEmptyOrWhitespace Property] | `($)TextIsEmptyOrWhitespace`, with no value | `($)TextIsEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`null` is not empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), resulting in the variable `($)TextIsEmptyOrWhitespace` being updated to the following: + +```json +false +``` + +*** + +### Text is not empty or whitespace + +This example will check if `"The quick brown fox jumps over the lazy dog"` is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text Is Empty Or Whitespace][TextIsEmptyOrWhitespace Property] | `($)TextIsEmptyOrWhitespace`, with no value | `($)TextIsEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), resulting in the variable `($)TextIsEmptyOrWhitespace` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text Is Empty Or Whitespace + +The result of the is empty or whitespace check. + +If the [Text][Text Property] is empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsEmptyOrWhitespace` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null Text + +If [Text][Text Property] is `null` the variable specified in the [Text Is Empty Or Whitespace][TextIsEmptyOrWhitespace Property] property will be set to `false`. See [Example][NullText Example] above. + +[Text Property]: {{< ref "#text" >}} +[TextIsEmptyOrWhitespace Property]: {{< ref "#text-is-empty-or-whitespace" >}} + +[NullText Example]: {{< ref "#text-is-null" >}} + +[Empty Text and Whitespace]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.EmptyTextAndWhitespace.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-equal-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-equal-block.md new file mode 100644 index 000000000..8f4954ce0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-equal-block.md @@ -0,0 +1,189 @@ +--- +title: "Is Text Equal" +linkTitle: "Is Text Equal" +description: "Checks if a text is equal to another text." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextEqualBlock)
+ +## Description + +Checks if [Text][Text Property] is equal to [Text To Compare][TextToCompare Property]. + +## Examples + +### Text is equal to Text To Compare (Ordinal) + +This example will check if `"The quick brown fox jumps over the lazy dog"` is equal to `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Compare][TextToCompare Property] | `($)TextToCompare`, with value `"The quick brown fox jumps over the lazy dog"` | `($)TextToCompare` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Text Is Equal][TextIsEqual Property] | `($)TextIsEqual`, with no value | `($)TextIsEqual` is a variable that will be set to a [Boolean][] value | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` is equal to `"The quick brown fox jumps over the lazy dog"`, as they match exactly, including casing. Therefore, the variable `($)TextIsEqual` will be updated to the following: + +```json +true +``` + +*** + +### Text is not equal to Text To Compare (Ordinal) + +This example will check if `"The quick brown fox jumps over the lazy dog"` is equal to `"the quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Compare][TextToCompare Property] | `($)TextToCompare`, with value `"the quick brown fox jumps over the lazy dog"` | `($)TextToCompare` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Text Is Equal][TextIsEqual Property] | `($)TextIsEqual`, with no value | `($)TextIsEqual` is a variable that will be set to a [Boolean][] value | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` is not equal to `"the quick brown fox jumps over the lazy dog"`, as whilst the characters match exactly, the casing of the first `"T"` differs. Therefore, the variable `($)TextIsEqual` will be updated to the following: + +```json +false +``` + +*** + +### Text is equal to Text To Compare (Ordinal Ignore Case) + +This example will check if `"The quick brown fox jumps over the lazy dog"` is equal to `"the quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Compare][TextToCompare Property] | `($)TextToCompare`, with value `"the quick brown fox jumps over the lazy dog"` | `($)TextToCompare` is a variable of type [String][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Text Is Equal][TextIsEqual Property] | `($)TextIsEqual`, with no value | `($)TextIsEqual` is a variable that will be set to a [Boolean][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` is equal to `"the quick brown fox jumps over the lazy dog"`, as the characters match exactly, and casing is not considered. Therefore, the variable `($)TextIsEqual` will be updated to the following: + +```json +true +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is equal to [Text To Compare][TextToCompare Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Compare + +The [Text To Compare][TextToCompare Property] if [Text][Text Property] is equal to. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to compare if [Text][Text Property] is equal to [Text To Compare][TextToCompare Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Text Is Equal + +[Boolean][] indicating whether [Text][Text Property] is equal to [Text To Compare][TextToCompare Property]. + +If they are equal the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsEqual` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null vs empty + +If [Text][Text Property] is `null` and [Text To Compare][TextToCompare Property] is empty (i.e. `""`), or vice versa, the variable specified in the [Text Is Equal][TextIsEqual Property] property is set to `false`, as `null` and `""` are not equal. + +[Text Property]: {{< ref "#text" >}} +[TextToCompare Property]: {{< ref "#text-to-compare" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[TextIsEqual Property]: {{< ref "#text-is-equal" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-block.md new file mode 100644 index 000000000..c8ff070b7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-block.md @@ -0,0 +1,165 @@ +--- +title: "Is Text Null" +linkTitle: "Is Text Null" +description: "Checks if text is `null`." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextNullBlock)
+ +## Description + +Checks if [Text][Text Property] is `null`. + +For information about `null`, please see [Null and Nullable Types][]. + +## Examples + +### Text is null + +This example will check if `null` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` | `($)Text` is a variable of type [String][] | +| [Text Is Null][TextIsNull Property] | `($)TextIsNull`, with no value | `($)TextIsNull` is a variable that will be set to a [Boolean][] value | + +#### Result + +`null` is `null`, resulting in the variable `($)TextIsNull` being updated to the following: + +```json +true +``` + +*** + +### Text is empty + +This example will check if empty (i.e. `""`) is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `""` | `($)Text` is a variable of type [String][] | +| [Text Is Null][TextIsNull Property] | `($)TextIsNull`, with no value | `($)TextIsNull` is a variable that will be set to a [Boolean][] value | + +#### Result + +Empty (i.e. `""`) is not `null`, resulting in the variable `($)TextIsNull` being updated to the following: + +```json +false +``` + +*** + +### Text is whitespace + +This example will check if `" "` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" "` | `($)Text` is a variable of type [String][] | +| [Text Is Null][TextIsNull Property] | `($)TextIsNull`, with no value | `($)TextIsNull` is a variable that will be set to a [Boolean][] value | + +#### Result + +`" "` is not `null`, resulting in the variable `($)TextIsNull` being updated to the following: + +```json +false +``` + +*** + +### Text is not null + +This example will check if `"The quick brown fox jumps over the lazy dog"` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text Is Null][TextIsNull Property] | `($)TextIsNull`, with no value | `($)TextIsNull` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not `null`, resulting in the variable `($)TextIsNull` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is `null`. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text Is Null + +The result of the is null check. + +If the [Text][Text Property] is `null`, the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsNull` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Empty Text + +If [Text][Text Property] is empty (i.e.. `""`) the variable specified in the [Text Is Null][TextIsNull Property] property will be set to `false`. See [Example][EmptyText Example] above. + +### Whitespace Text + +If [Text][Text Property] is whitespace (e.g. `" "`) the variable specified in the [Text Is Null][TextIsNull Property] property will be set to `false`. See [Example][WhitespaceText Example] above. + +[Text Property]: {{< ref "#text" >}} +[TextIsNull Property]: {{< ref "#text-is-null-1" >}} + +[EmptyText Example]: {{< ref "#text-is-empty" >}} +[WhitespaceText Example]: {{< ref "#text-is-whitespace" >}} + +[Null and Nullable Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.NullAndNullableTypes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-empty-or-whitespace-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-empty-or-whitespace-block.md new file mode 100644 index 000000000..ebc859816 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-empty-or-whitespace-block.md @@ -0,0 +1,160 @@ +--- +title: "Is Text Null, Empty Or Whitespace" +linkTitle: "Is Text Null, Empty Or Whitespace" +description: "Checks if text is `null`, empty (i.e. `\"\"`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters)." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextNullEmptyOrWhitespaceBlock)
+ +## Description + +Checks if [Text][Text Property] is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +For information about `null`, please see [Null and Nullable Types][]. + +For information about empty and whitespace, please see [Empty Text and Whitespace][]. + +## Examples + +### Text is null + +This example will check if `null` is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` | `($)Text` is a variable of type [String][] | +| [Text Is Null Empty Or Whitespace][TextIsNullEmptyOrWhitespace Property] | `($)TextIsNullEmptyOrWhitespace`, with no value | `($)TextIsNullEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`null` is `null`, resulting in the variable `($)TextIsNullEmptyOrWhitespace` being updated to the following: + +```json +true +``` + +*** + +### Text is empty + +This example will check if `""` is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `""` | `($)Text` is a variable of type [String][] | +| [Text Is Null Empty Or Whitespace][TextIsNullEmptyOrWhitespace Property] | `($)TextIsNullEmptyOrWhitespace`, with no value | `($)TextIsNullEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`""` is empty (i.e. `""`), resulting in the variable `($)TextIsNullEmptyOrWhitespace` being updated to the following: + +```json +true +``` + +*** + +### Text is whitespace + +This example will check if `" "` is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" "` | `($)Text` is a variable of type [String][] | +| [Text Is Null Empty Or Whitespace][TextIsNullEmptyOrWhitespace Property] | `($)TextIsNullEmptyOrWhitespace`, with no value | `($)TextIsNullEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`" "` is whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), resulting in the variable `($)TextIsNullEmptyOrWhitespace` being updated to the following: + +```json +true +``` + +*** + +### Text is not null, empty or whitespace + +This example will check if `"The quick brown fox jumps over the lazy dog"` is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text Is Null Empty Or Whitespace][TextIsNullEmptyOrWhitespace Property] | `($)TextIsNullEmptyOrWhitespace`, with no value | `($)TextIsNullEmptyOrWhitespace` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), resulting in the variable `($)TextIsNullEmptyOrWhitespace` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters). + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text Is Null Empty Or Whitespace + +The result of the is null, empty or whitespace check. + +If the [Text][Text Property] is `null`, empty (i.e. `""`) or whitespace (i.e. `space`, `tab`, `carriage return`, `line feed` characters), the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsNullEmptyOrWhitespace` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +None + +[Text Property]: {{< ref "#text" >}} +[TextIsNullEmptyOrWhitespace Property]: {{< ref "#text-is-null-empty-or-whitespace" >}} + +[Null and Nullable Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.NullAndNullableTypes.MainDoc" >}} + +[Empty Text and Whitespace]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.EmptyTextAndWhitespace.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-or-empty-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-or-empty-block.md new file mode 100644 index 000000000..9261428a9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/is-text/is-text-null-or-empty-block.md @@ -0,0 +1,164 @@ +--- +title: "Is Text Null Or Empty" +linkTitle: "Is Text Null Or Empty" +description: "Checks if text is `null` or empty (i.e. `\"\"`)." +--- + +{{< figure src="/blocks/text-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.IsText.IsTextNullOrEmptyBlock)
+ +## Description + +Checks if [Text][Text Property] is `null` or empty (i.e. `""`). + +For information about `null`, please see [Null and Nullable Types][]. + +For information about empty, please see [Empty Text and Whitespace][]. + +## Examples + +### Text is null + +This example will check if `null` is `null` or empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `null` | `($)Text` is a variable of type [String][] | +| [Text Is Null Or Empty][TextIsNullOrEmpty Property] | `($)TextIsNullOrEmpty`, with no value | `($)TextIsNullOrEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`null` is `null`, resulting in the variable `($)TextIsNullOrEmpty` being updated to the following: + +```json +true +``` + +*** + +### Text is empty + +This example will check if `""` is `null` or empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `""` | `($)Text` is a variable of type [String][] | +| [Text Is Null Or Empty][TextIsNullOrEmpty Property] | `($)TextIsNullOrEmpty`, with no value | `($)TextIsNullOrEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`""` is empty (i.e. `""`), resulting in the variable `($)TextIsNullOrEmpty` being updated to the following: + +```json +true +``` + +*** + +### Text is whitespace + +This example will check if `" "` is `null` or empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" "` | `($)Text` is a variable of type [String][] | +| [Text Is Null Or Empty][TextIsNullOrEmpty Property] | `($)TextIsNullOrEmpty`, with no value | `($)TextIsNullOrEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`" "` is not `null` or empty (i.e. `""`), resulting in the variable `($)TextIsNullOrEmpty` being updated to the following: + +```json +false +``` + +*** + +### Text is not null or empty + +This example will check if `"The quick brown fox jumps over the lazy dog"` is `null` or empty (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text Is Null Or Empty][TextIsNullOrEmpty Property] | `($)TextIsNullOrEmpty`, with no value | `($)TextIsNullOrEmpty` is a variable that will be set to a [Boolean][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not `null` or empty (i.e. `""`), resulting in the variable `($)TextIsNullOrEmpty` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to check is `null` or empty (i.e. `""`). + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text Is Null Or Empty + +The result of the is null or empty check. + +If the [Text][Text Property] is `null` or empty (i.e. `""`), the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TextIsNullOrEmpty` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Whitespace Text + +If [Text][Text Property] is whitespace (e.g. `" "`) the variable specified in the [Text Is Null Or Empty][TextIsNullOrEmpty Property] property will be set to `false`. See [Example][WhitespaceText Example] above. + +[Text Property]: {{< ref "#text" >}} +[TextIsNullOrEmpty Property]: {{< ref "#text-is-null-or-empty" >}} + +[WhitespaceText Example]: {{< ref "#text-is-whitespace" >}} + +[Null and Nullable Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.NullAndNullableTypes.MainDoc" >}} + +[Empty Text and Whitespace]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.EmptyTextAndWhitespace.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/join-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/join-text/_index.md new file mode 100644 index 000000000..60c7d1193 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/join-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Join Text" +linkTitle: "Join Text" +description: "Join a set of values together (using a separator) to create text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/join-text/join-text-block-1.md b/content/en/docs/2023.9/Reference/Blocks/Text/join-text/join-text-block-1.md new file mode 100644 index 000000000..a2b682dd8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/join-text/join-text-block-1.md @@ -0,0 +1,154 @@ +--- +title: "Join Text" +linkTitle: "Join Text" +description: "Joins a set of values together as text, using the given separator between each value." +--- + +{{< figure src="/blocks/text-join-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.JoinText.JoinTextBlock`1)
+ +## Description + +Joins a set of [Values][Values Property] together as [Text][Text Property], using the given [Separator][Separator Property] between each value. + +## Examples + +### Join a set of String Values together with a pipe Separator + +This example will join the set of [String][] values, `["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]`, together with a pipe separator (i.e. `"|"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Values][Values Property] | `($)Values`, with value `["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]` | `($)Values` is a variable of type [IEnumerable][]<[String][]> | +| [Separator][Separator Property] | `($)Separator`, with value `"\|"` | `($)Separator` is a variable of type [String][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] | + +#### Result + +Joining `["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]` together as text with a pipe separator (i.e. `"|"`), results in the variable `($)Text` being updated to the following: + +```json +"Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday" +``` + +*** + +### Join a set of Int32 Values together with a comma Separator + +This example will join the set of [Int32][] values, `[1, 2, 3]`, together with a comma separator (i.e. `","`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Values][Values Property] | `($)Values`, with value `[1, 2, 3]` | `($)Values` is a variable of type [IEnumerable][]<[Int32][]> | +| [Separator][Separator Property] | `($)Separator`, with value `","` | `($)Separator` is a variable of type [String][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] | + +#### Result + +Each [Int32][] value will be converted to its text representation, by calling its [ToString][] method (i.e. `value.ToString()`). + +Joining `[1, 2, 3]` together as text with a comma separator (i.e. `","`), results in the variable `($)Text` being updated to the following: + +```json +"1,2,3" +``` + +*** + +## Properties + +### Values + +The set of [Values][Values Property] to join together as [Text][Text Property]. + +[Values][Values Property] will be joined together in the order they are defined. + +[Values][Values Property] can be any [IEnumerable][]<[TValue][]>, where [TValue][] represents the type of values. + +Each non-text value will be converted to its text representation, by calling its [ToString][] method (i.e. `value.ToString()`). + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][]<[TValue][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Values` with no value | + +### Separator + +The text to use as a [Separator][Separator Property] between each of the [Values][Values Property]. + +[Separator][Separator Property] can contain zero or more characters. + +The [Separator][Separator Property] is only included in the resultant [Text][Text Property] if [Values][Values Property] has more than `1` item. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `,` | + +### Text + +The resultant [Text][Text Property] containing the specified [Values][Values Property] converted to their text representation and separated by the given [Separator][Separator Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Values][Values Property] is `null`. | +| [OutOfMemoryException][] | Thrown when the length of the resultant [Text][Text Property] is longer than the maximum allowed length (`2,147,483,647`). | + +## Remarks + +### Null or empty Separator + +If [Separator][Separator Property] is `null` or empty (i.e. `""`), an empty text (i.e. `""`) will be used as the separator. + +### Null or empty Value in Values + +If any value in [Values][Values Property] is `null` or empty (i.e. `""`), an empty text (i.e. `""`) will be used as the value. + +[Values Property]: {{< ref "#values" >}} +[Separator Property]: {{< ref "#separator" >}} +[Text Property]: {{< ref "#text" >}} + +[TValue]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[OutOfMemoryException]: {{< url path="MSDocs.DotNet.Api.System.OutOfMemoryException" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[ToString]: {{< url path="MSDocs.DotNet.Api.System.Object.ToString" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/_index.md new file mode 100644 index 000000000..73ba8925c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Remove Text" +linkTitle: "Remove Text" +description: "Remove a length of text from a given text." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-beginning-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-beginning-block.md new file mode 100644 index 000000000..91e645abe --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-beginning-block.md @@ -0,0 +1,106 @@ +--- +title: "Remove Text At Beginning" +linkTitle: "Remove Text At Beginning" +description: "Removes a length of text from the beginning of a given text." +--- + +{{< figure src="/blocks/text-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.RemoveText.RemoveTextAtBeginningBlock)
+ +## Description + +Removes a [Length][Length Property] of text from the beginning of a given [Text][Text Property]. + +## Examples + +### Remove a Length of text from the beginning of a given Text + +This example will remove the first `3` characters from the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | + +#### Result + +Removing the first `3` characters from the beginning of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)Text` being updated to the following: + +```json +"DEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to remove the [Length][Length Property] of text from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Length + +The [Length][Length Property] of text to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Length][Length Property] is greater than the length of [Text][Text Property]. | + +## Remarks + +### Negative Length + +If [Length][Length Property] is negative, all text will be removed and the variable specified in the [Text][Text Property] property will be set to empty (i.e. `""`). + +### Zero Length + +If [Length][Length Property] is `0`, no text will be removed and the variable specified in the [Text][Text Property] property will remain unchanged. + +[Text Property]: {{< ref "#text" >}} +[Length Property]: {{< ref "#length" >}} + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Length][Length Property] of text removed at the beginning and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-end-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-end-block.md new file mode 100644 index 000000000..cbb6e6efa --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-end-block.md @@ -0,0 +1,106 @@ +--- +title: "Remove Text At End" +linkTitle: "Remove Text At End" +description: "Removes a length of text from the end of a given text." +--- + +{{< figure src="/blocks/text-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.RemoveText.RemoveTextAtEndBlock)
+ +## Description + +Removes a [Length][Length Property] of text from the end of a given [Text][Text Property]. + +## Examples + +### Remove a Length of text from the end of a given Text + +This example will remove the last `3` characters from the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | + +#### Result + +Removing the last `3` characters from the end of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` results in the variable `($)Text` being updated to the following: + +```json +"ABCDEFGHIJKLMNOPQRSTUVW" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to remove the [Length][Length Property] of text from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Length + +The [Length][Length Property] of text to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Length][Length Property] is greater than the length of [Text][Text Property]. | + +## Remarks + +### Negative Length + +If [Length][Length Property] is negative, all text will be removed and the variable specified in the [Text][Text Property] property will be set to empty (i.e. `""`). + +### Zero Length + +If [Length][Length Property] is `0`, no text will be removed and the variable specified in the [Text][Text Property] property will remain unchanged. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Length][Length Property] of text removed at the end and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[Length Property]: {{< ref "#length" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-index-block.md new file mode 100644 index 000000000..c3dd0026e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-at-index-block.md @@ -0,0 +1,128 @@ +--- +title: "Remove Text At Index" +linkTitle: "Remove Text At Index" +description: "Removes a length of text at the specified index of a given text." +--- + +{{< figure src="/blocks/text-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.RemoveText.RemoveTextAtIndexBlock)
+ +## Description + +Removes a [Length][Length Property] of text at the specified [Index][Index Property] of a given [Text][Text Property]. + +## Examples + +### Remove a Length of text at the specified Index of a given Text + +This example will remove `3` characters at index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `3` | `($)Index` is a variable of type [Int32][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | + +#### Result + +`"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, removing `3` characters at (and including) index `3` results in the variable `($)Text` being updated to the following: + +```json +"ABCGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to remove the [Length][Length Property] of text from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Index + +The [Index][Index Property] to remove the text from. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Length + +The [Length][Length Property] of text to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | +| | Thrown when [Index][Index Property] + a positive [Length][Length Property] is greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Negative Length + +A negative [Length][Length Property] can be used to remove all text at and after the [Index][Index Property] of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, no text will be removed and the variable specified in the [Text][Text Property] property will remain unchanged. + +### Index is inclusive + +The [Index][Index Property] property is an inclusive [index][Indexes], which means the character at the index will be included in the removed text. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Length][Length Property] of text removed at the specified [Index][Index Property] and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[Index Property]: {{< ref "#index" >}} +[Length Property]: {{< ref "#length" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-before-index-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-before-index-block.md new file mode 100644 index 000000000..50c2cda31 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-before-index-block.md @@ -0,0 +1,129 @@ +--- +title: "Remove Text Before Index" +linkTitle: "Remove Text Before Index" +description: "Removes a length of text before the specified index of a given text." +--- + +{{< figure src="/blocks/text-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.RemoveText.RemoveTextBeforeIndexBlock)
+ +## Description + +Removes a [Length][Length Property] of text before the specified [Index][Index Property] of a given [Text][Text Property]. + +## Examples + +### Remove a Length of text before the specified Index of a given Text + +This example will remove `3` characters before index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Index][Index Property] | `($)Index`, with value `3` | `($)Index` is a variable of type [Int32][] | +| [Length][Length Property] | `($)Length`, with value `3` | `($)Length` is a variable of type [Int32][] | + +#### Result + +`"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, removing `3` characters before index `3` results in the variable `($)Text` being updated to the following: + +```json +"DEFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to remove the [Length][Length Property] of text from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + + +### Index + +The [Index][Index Property] to remove the text before. This is an exclusive index, which means the character at the specified index won't be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Length + +The [Length][Length Property] of text to remove. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `-1` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Index][Index Property] is less than `1` or greater than the length of [Text][Text Property] - `1`. | +| | Thrown when [Index][Index Property] - a positive [Length][Length Property] is less than `1`. | + +## Remarks + +### Negative Length + +A negative [Length][Length Property] can be used to remove all text before the [Index][Index Property] of [Text][Text Property]. + +### Zero Length + +If [Length][Length Property] is `0`, the variable specified in the [Text][Text Property] property will be set to empty (i.e. `""`). + +### Index is exclusive + +The [Index][Index Property] property is an exclusive [index][Indexes], which means the character at the index will not be included in the removed text. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the [Length][Length Property] of text removed before the specified [Index][Index Property] and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[Index Property]: {{< ref "#index" >}} +[Length Property]: {{< ref "#length" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-between-indexes-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-between-indexes-block.md new file mode 100644 index 000000000..95585f95d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/remove-text/remove-text-between-indexes-block.md @@ -0,0 +1,155 @@ +--- +title: "Remove Text Between Indexes" +linkTitle: "Remove Text Between Indexes" +description: "Removes text between the specified start index and end index of a given text." +--- + +{{< figure src="/blocks/text-remove-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.RemoveText.RemoveTextBetweenIndexesBlock)
+ +## Description + +Removes text between the specified [Start Index][StartIndex Property] and [End Index][EndIndex Property] of a given [Text][Text Property]. + +## Examples + +### Remove text between the specified Start Index and End Index of a given Text + +This example will remove all characters between start index `0` and end index `3` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `0` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `3` | `($)EndIndex` is a variable of type [Int32][] | + +#### Result + +`"A"` is at index `0` and `"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. Therefore, removing all characters between (and including) start index `0` and end index `3` results in the variable `($)Text` being updated to the following: + +```json +"EFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +### Remove text where Start Index is greater than End Index + +This example will remove all characters between start index `3` and end index `0` of `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` | `($)Text` is a variable of type [String][] | +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `3` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `0` | `($)EndIndex` is a variable of type [Int32][] | + +#### Result + +In this example the start index `3` is greater than the end index `0`. When this occurs, the block simply swaps the indexes before it processes the text. + +Therefore, having start index `3` and end index `0` is the same as having start index `0` and end index `3`. + +`"A"` is at index `0` and `"D"` is at index `3` in `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`. + +Therefore, removing all characters between (and including) start index `3` and end index `0`, or start index `0` and end index `3`, results in the variable `($)Text` being updated to the following: + +```json +"EFGHIJKLMNOPQRSTUVWXYZ" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to remove the text from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Start Index + +The [Start Index][StartIndex Property] used to remove the text. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### End Index + +The [End Index][EndIndex Property] used to remove the text. This is an inclusive index, which means the character at the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when [Text][Text Property] is `null` or empty (i.e. `""`). | +| | Thrown when [Start Index][StartIndex Property] or [End Index][EndIndex Property] is less than zero or greater than the length of [Text][Text Property] - `1`. | + +## Remarks + +### Start Index and End Index are inclusive + +The [Start Index][StartIndex Property] and [End Index][EndIndex Property] properties are both inclusive [indexes][Indexes], which means the characters at those indexes will be included in the removed text. + +### Start Index greater than End Index + +[Start Index][StartIndex Property] can be greater than [End Index][EndIndex Property]. If this is the case, the values of the indexes will be swapped. See [Example][StartIndexGreaterThanEndIndex Example] above. + +### Immutable String data type + +The [String][] data type used to represent [Text][Text Property] is immutable, which means it is read-only and cannot be changed once created. + +To overcome this, this block creates a new [String][] which has the text removed between the specified [Start Index][StartIndex Property] and [End Index][EndIndex Property], and re-assigns it to the variable specified in the [Text][Text Property] property. + +[Text Property]: {{< ref "#text" >}} +[StartIndex Property]: {{< ref "#start-index" >}} +[EndIndex Property]: {{< ref "#end-index" >}} + +[StartIndexGreaterThanEndIndex Example]: {{< ref "#remove-text-where-start-index-is-greater-than-end-index" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/split-text/_index.md b/content/en/docs/2023.9/Reference/Blocks/Text/split-text/_index.md new file mode 100644 index 000000000..498cf5969 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/split-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Split Text" +linkTitle: "Split Text" +description: "Split text (using a separator) into a list of values." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/Text/split-text/split-text-block.md b/content/en/docs/2023.9/Reference/Blocks/Text/split-text/split-text-block.md new file mode 100644 index 000000000..fe597818b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/Text/split-text/split-text-block.md @@ -0,0 +1,244 @@ +--- +title: "Split Text" +linkTitle: "Split Text" +description: "Splits text into a list of String values, using the given separator to determine where to split." +--- + +{{< figure src="/blocks/text-split-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Text.SplitText.SplitTextBlock)
+ +## Description + +Splits [Text][Text Property] into a list of [String][] [Values][Values Property], using the given [Separator][Separator Property] to determine where to split. + +[Split Options][SplitOptions Property] can be used to specify how to treat empty entries (i.e. `""`). + +## Examples + +### Split Text into a list of String Values using a pipe Separator + +This example will split the text `"Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday"` into a list of [String][] values, using the pipe separator (i.e. `"|"`) to determine where to split. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"Sunday\|Monday\|Tuesday\|Wednesday\|Thursday\|Friday\|Saturday"` | `($)Text` is a variable of type [String][] | +| [Separator][Separator Property] | `($)Separator`, with value `"\|"` | `($)Separator` is a variable of type [String][] | +| [Split Options][SplitOptions Property] | `($)SplitOptions`, with value `StringSplitOptions.None` | `($)SplitOptions` is a variable of type [StringSplitOptions][] | +| [Values][Values Property] | `($)Values`, with no value | `($)Values` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Splitting `"Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday"` using a pipe separator (i.e. `"|"`), results in the variable `($)Values` being updated to the following: + +```json +["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"] +``` + +*** + +### Split Text into a list of String Values using a comma Separator (removing empty entries) + +This example will split the text `"1,2,3,,"` into a list of [String][] values, using the comma separator (i.e. `","`) to determine where to split, and removing empty entries (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"1,2,3,,"` | `($)Text` is a variable of type [String][] | +| [Separator][Separator Property] | `($)Separator`, with value `","` | `($)Separator` is a variable of type [String][] | +| [Split Options][SplitOptions Property] | `($)SplitOptions`, with value `StringSplitOptions.RemoveEmptyEntries` | `($)SplitOptions` is a variable of type [StringSplitOptions][] | +| [Values][Values Property] | `($)Values`, with no value | `($)Values` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Splitting `"1,2,3,,"` using a comma separator (i.e. `","`) and removing the last 2 entries which are empty (i.e. `""`), results in the variable `($)Values` being updated to the following: + +```json +["1", "2", "3"] +``` + +*** + +### Split Text into a list of String Values using a comma Separator (keeping empty entries) + +This example will split the text `"1,2,3,,"` into a list of [String][] values, using the comma separator (i.e. `","`) to determine where to split, and keeping empty entries (i.e. `""`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"1,2,3,,"` | `($)Text` is a variable of type [String][] | +| [Separator][Separator Property] | `($)Separator`, with value `","` | `($)Separator` is a variable of type [String][] | +| [Split Options][SplitOptions Property] | `($)SplitOptions`, with value `StringSplitOptions.None` | `($)SplitOptions` is a variable of type [StringSplitOptions][] | +| [Values][Values Property] | `($)Values`, with no value | `($)Values` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Splitting `"1,2,3,,"` using a comma separator (i.e. `","`) and keeping the last 2 entries which are empty but trimming, results in the variable `($)Values` being updated to the following: + +```json +["1", "2", "3", "", ""] +``` + +*** + +### Split Text into a list of String Values using a comma Separator (keeping empty entries but trimming entries) + +This example will split the text `" 1 , 2,3 ,,"` into a list of [String][] values, using the comma separator (i.e. `","`) to determine where to split, and keeping empty entries (i.e. `""`) but trimming whitespaces (i.e. `" 1 "` would become `"1"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" 1 , 2,3 ,,"` | `($)Text` is a variable of type [String][] | +| [Separator][Separator Property] | `($)Separator`, with value `","` | `($)Separator` is a variable of type [String][] | +| [Split Options][SplitOptions Property] | `($)SplitOptions`, with value `StringSplitOptions.TrimEntries` | `($)SplitOptions` is a variable of type [StringSplitOptions][] | +| [Values][Values Property] | `($)Values`, with no value | `($)Values` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Splitting `" 1 , 2,3 ,,"` using a comma separator (i.e. `","`) and keeping the last 2 entries which are empty (i.e. `""`) but trimming whitespaces (i.e. `" 1 "`), results in the variable `($)Values` being updated to the following: + +```json +["1", "2", "3", "", ""] +``` + +*** + +### Split Text into a list of String Values using a comma Separator (removing empty entries and trimming entries) + +This example will split the text `" 1 , 2,3 ,,"` into a list of [String][] values, using the comma separator (i.e. `","`) to determine where to split, and remove any empty entries (i.e. `""`) and trimming whitespaces (i.e. `" 1 "` would become `"1"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `" 1 , 2,3 ,,"` | `($)Text` is a variable of type [String][] | +| [Separator][Separator Property] | `($)Separator`, with value `","` | `($)Separator` is a variable of type [String][] | +| [Split Options][SplitOptions Property] | `($)SplitOptions`, with value `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | `($)SplitOptions` is a variable of type [StringSplitOptions][] | +| [Values][Values Property] | `($)Values`, with no value | `($)Values` is a variable that will be set to an [IList][]<[String][]> | + +#### Result + +Splitting `" 1 , 2,3 ,,"` using a comma separator (i.e. `","`) and removing the last 2 entries which are empty (i.e. `""`) and trimming whitespaces (i.e. `" 1 "`), results in the variable `($)Values` being updated to the following: + +```json +["1", "2", "3"] +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to split into [Values][Values Property] using the given [Separator][Separator Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Separator + +The [Separator][Separator Property] used to determine where to split the [Text][Text Property] into the [Values][Values Property]. + +[Separator][Separator Property] can contain zero or more characters. + +The [Separator][Separator Property] is not included in the resultant [Values][Values Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `,` | + +### Split Options + +[Split Options][SplitOptions Property] used to specify how to treat empty entries (i.e. `""`). + +Currently supported values for the [Split Options][SplitOptions Property] property are: + +* StringSplitOptions.None (Default) - empty entries and trailing or leading whitespaces (at the start or end of text) are included in [Values][Values Property]. +* StringSplitOptions.RemoveEmptyEntries - empty entries are excluded from [Values][Values Property]; trailing or leading whitespaces (at the start or end of text) are included. +* StringSplitOptions.TrimEntries - trailing or leading whitespaces (at the start or end of text) are excluded from [Values][Values Property]; empty entries are included. + +It's also possible to combine `StringSplitOptions` in the [Expression Editor][Expression]. The example below shows how to remove empty entries and trim entries: + +```csharp +StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries +``` + +| | | +|--------------------|---------------------------| +| Data Type | [StringSplitOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `None` | + +### Values + +The resultant [Values][Values Property] containing an entry for each piece of split text in the order they are defined in [Text][Text Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Values` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Split Options][SplitOptions Property] is not one of the specified [StringSplitOptions][] types (e.g. `(StringSplitOptions)10`). | + +## Remarks + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`), then `null` or empty (i.e. `""`) respectively is added as the only entry to [Values][Values Property]. + +### Null or empty Separator + +If [Separator][Separator Property] is `null` or empty (i.e. `""`), the value of the variable specified for the [Text][Text Property] property is added as the only entry to [Values][Values Property]. + +### Separator not found + +If the [Separator][Separator Property] is not found in [Text][Text Property], the value of the variable specified for the [Text][Text Property] property is added as the only entry to [Values][Values Property]. + +[Values Property]: {{< ref "#values" >}} +[Separator Property]: {{< ref "#separator" >}} +[SplitOptions Property]: {{< ref "#split-options" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[StringSplitOptions]: {{< url path="Cortex.Reference.DataTypes.Text.StringSplitOptions.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + diff --git a/content/en/docs/2023.9/Reference/Blocks/_index.md b/content/en/docs/2023.9/Reference/Blocks/_index.md new file mode 100644 index 000000000..321f178f6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/_index.md @@ -0,0 +1,6 @@ +--- +title: "Blocks" +linkTitle: "Blocks" +description: "This section includes all reference documentation for functional blocks." +weight: 10 +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/data-storage/_index.md b/content/en/docs/2023.9/Reference/Blocks/data-storage/_index.md new file mode 100644 index 000000000..1ec60a4e9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/data-storage/_index.md @@ -0,0 +1,5 @@ +--- +title: "Data Storage" +linkTitle: "Data Storage" +description: "Blocks related to working with Data Storage." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/_index.md b/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/_index.md new file mode 100644 index 000000000..7d76634a0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/_index.md @@ -0,0 +1,5 @@ +--- +title: "Create Collection" +linkTitle: "Create Collection" +description: "Create a data storage collection." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md b/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md new file mode 100644 index 000000000..bc6739994 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md @@ -0,0 +1,133 @@ +--- +title: "Create Collection" +linkTitle: "Create Collection" +description: "Create a data storage collection." +--- +{{(Cortex.Blocks.DataStorage.CreateCollection.CreateCollectionBlock)
+ +## Description + +Create a [Data Storage Collection] within the [Collection Scope][Collection Scope Property]. + +## Examples + +### Create a Data Storage Collection + +This example will attempt to create a new [Data Storage Collection] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock)
+ +## Description + +Delete a [Data Storage Collection][] within the [Collection Scope][Collection Scope Property]. + +## Examples + +### Delete a Data Storage Collection + +This example will attempt to delete a [Data Storage Collection] named `"users"`that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. +In this example `"users"` already exists. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock)
+ +## Description + +Deletes data from a [Data Storage Collection][] with the specified [Key][Key Property]. + +## Examples + +### Delete from a Data Storage Collection + +This example will attempt to delete data from a [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. In this example `"users"` already exists and contains the following [Keys][Key Property] and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +The example will delete the [Key][Key Property] `"user2"` and the associated data. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock)
+ +## Description + +Reads data from a [Data Storage Collection][] with the specified [Key][Key Property]. + +## Examples + +### Read from a Data Storage Collection + +This example will attempt to read [Data][Data Property] from a [Data Storage Collection] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. In this example `"users"` already exists and contains the following [Keys][Key Property] and [Data][Data Property]: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +The example will read the [Key][Key Property] `"user2"` and store the retrieved [Data][Data Property] to `($)Data`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForCollection.WaitForCollectionToExistBlock)
+ +## Description + +Waits for a specified [Data Storage Collection][] to exist within a [Collection Scope][Collection Scope Property]. + +## Examples + +### Wait for a Data Storage Collection to exist + +This example will wait for a [Data Storage Collection][] `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [CollectionScope][Collection Scope Property], to exist. In this example `"users"` does not already exist. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForCollection.WaitForCollectionToNotExistBlock)
+ +## Description + +Waits for a specified [Data Storage Collection][] to not exist within a [Collection Scope][Collection Scope Property]. + +## Examples + +### Wait for a Data Storage Collection to not exist + +This example will wait for a [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property], to not exist. In this example `"users"` already exists and contains the following keys and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToBeSetBlock)
+ +## Description + +Waits for a specified [Key][Key Property] in a [Data Storage Collection][] within a [Collection Scope][Collection Scope Property] to be set to a value and returns the [old][Old Value Property] and [new][New Value Property] values. + +## Examples + +### Wait for a Key to be set in a Data Storage Collection + +This example will wait for a [Key][Key Property] `"user1"` to be set in a [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. In this example `"users"` already exists and contains the following following keys and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +In this example a separate flow with access to `"users"` has a [Write Data With Key][Write Data With Key] block that will act on `"users"` to update the following key and data: +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "newDomain", "Username": "newUser1", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToContainValueBlock)
+ +## Description + +Waits for a given [Key][Key Property] to contain the specified [Value][Value Property] in a [Data Storage Collection][] within a [Collection Scope][Collection Scope Property]. + +## Examples + +### Wait for a Key in a Data Storage Collection to contain Value + +This example will wait for a [Key][Key Property] `"user2"` to contain the [Value][Value Property] `{"Domain": "domain", "Username": "admin", "Password": "encryptedPassword"}` in the [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. +In this example `"users"` already exists and contains the following keys and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToExistBlock)
+ +## Description + +Waits for a specified [Key][Key Property] to exist in a [Data Storage Collection][] within a [Collection Scope][Collection Scope Property]. + +## Examples + +### Wait for a Key to exist in a Data Storage Collection + +This example will wait for a [Key][Key Property] `"user3"` to exist in a [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. In this example `"users"` already exists and contains the following following keys and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToNotExistBlock)
+ +## Description + +Waits for a specified [Key][Key Property] to not exist in a [Data Storage Collection][] within a [Collection Scope][Collection Scope Property]. + +## Examples + +### Wait for a Key in a Data Storage Collection to not exist + +This example will wait for a [Key][Key Property] `"user2"` to exist in the [Data Storage Collection][] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. +In this example `"users"` already exists and contains the following keys and data: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock)
+ +## Description + +Writes [Data][Data Property] to a [Data Storage Collection][] with the specified [Key][Key Property]. + +## Examples + +### Write to a Data Storage Collection + +This example will attempt to write [Data][Data Property] to a [Data Storage Collection] named `"users"` that is only accessible by flows that are scoped to the same [Tenant] and [System] specified by the [Collection Scope][Collection Scope Property]. In this example `"users"` already exists and contains the following [Keys][Key Property] and [Data][Data Property]: + + |Key | Data | +-------------|--------------| + |`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | + +The example will write the [Data][Data Property] `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` of type [UserCredentials][] with the [Key][Key Property] `"user2"`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current"}`.(Cortex.Blocks.Data.ExecuteDataCommand.ExecuteDataCommandBlock`1)
+ +## Description + +Connects to a data source (e.g. SQL Server) using the specified [Connection Details][Connection Details Property], and executes a [Command][Command Property] (e.g. `SELECT * FROM Table`), returning the [Result][Result Property]. + +[Close Connection][Close Connection Property] can be specified to choose whether the connection to the data source is closed or is kept open for use on subsequent Execute Command blocks. + +## Examples + +### Selecting Rows + +This example will select all rows and columns from a connected SQL Server data source which have an Id less than 3, saving the rows to the [Result][Result Property]. + +A [QueryCommand][Command Types QueryCommand] is used throughout this example to select data from the data source, however, both an [Command][Command Types Command] or [Commands][Command Types Commands] could also be used to the same effect. + +The data source contains a `Table` with the following rows and columns before the command is executed: +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `1` | `"FirstColumn1"` | `"SecondColumn1"` | +| `2` | `"FirstColumn2"` | `"SecondColumn2"` | +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Command][Command Property] | `($)Command`, with value `{"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}}`(Cortex.Blocks.DateAndTime.AddTimePeriod.AddTimePeriodBlock)
+ +## Description + +Adds a [Time Period][TimePeriod Property] to the specified [Date Time][DateTime Property]. + +This block can add both positive and negative [TimePeriod][] values. + +## Examples + +### Add a positive Time Period + +This example will add `1 year`, `1 month`, `1 day`, `1 hour` and `30 minutes` to `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Time Period][TimePeriod Property] | `($)TimePeriod`, with value of `{"Years": 1, "Months": 1, "Days": 1, "Hours": 1, "Minutes": 30, "Seconds": 0, "Milliseconds": 0}` | `($)TimePeriod` is a variable of type [TimePeriod][] | + +#### Result + +Adding `1 year`, `1 month`, `1 day`, `1 hour` and `30 minutes` to `2021-01-01T00:00:00+00:00` will result in the variable `($)DateTime` being updated. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2022-02-02T01:30:00+00:00" +``` + +*** + +### Add a negative Time Period + +This example will add `-1 year` to `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Time Period][TimePeriod Property] | `($)TimePeriod`, with value of `{"Years": -1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}` | `($)TimePeriod` is a variable of type [TimePeriod][] | + +#### Result + +Adding `-1 year` from `2021-01-01T00:00:00+00:00` will result in `1 year` being subtracted and the variable `($)DateTime` being updated. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2020-01-01T00:00:00+00:00" +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to add the [Time Period][TimePeriod Property] to. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Time Period + +The [Time Period][TimePeriod Property] to add to the [Date Time][DateTime Property] to. + +[Time Period][TimePeriod Property] can have positive and negative components where components are: + +* Years +* Months +* Days +* Hours +* Minutes +* Seconds +* Milliseconds + +When adding a [Time Period][TimePeriod Property], the block will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds. + +When adding months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. adding one month onto `2021-01-31T23:59:59+00:00` will equate to `2021-02-28T23:59:59+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TimePeriod][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | Years: `0`(Cortex.Blocks.DateAndTime.ConvertDateTime.ConvertDateTimeToTextBlock)
+ +## Description + +Converts a [Date Time][DateTime Property] to [Text][Text Property]. + +Additional options can be specified: + +* [Format Template][FormatTemplate Property] can be specified to define the format the [Date Time][DateTime Property] should be converted to (e.g. `"dd/MM/yyyy"`). +* [Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting). + +## Examples + +### ISO 8601 Standard Format + +This example will convert a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset) to the [ISO 8601 Standard][] format (i.e. `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `null` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting a Date Time representing midnight on 31st December 2021 (with a `0` UTC time offset and without specifying any format template or provider) will result in the variable `($)Text` being updated to the following [ISO 8601 Standard][] text representation: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +### Default format for Invariant Culture + +This example will convert a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset) to the default format for Invariant Culture (i.e. `"MM/dd/yyyy HH:mm:ss zzz"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `CultureInfo.InvariantCulture` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting a Date Time representing midnight on 31st December 2021 (with a `0` UTC time offset and without a format template), but specifying Invariant Culture text representation, will result in the variable `($)Text` being updated to the following: + +```json +"12/31/2021 00:00:00 +00:00" +``` + +*** + +### Full Date Long Time format for Invariant Culture + +This example will convert a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset) to the Full Date Long Time format for Invariant Culture (i.e. `"dddd, dd MMMM yyyy HH:mm:ss"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"F"` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `CultureInfo.InvariantCulture` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting a Date Time representing midnight on 31st December 2021 (with a `0` UTC time offset), and specifying the Full Date Long Time format for Invariant Culture, will result in the variable `($)Text` being updated to the following: + +```json +"Friday, 31 December 2021 00:00:00" +``` + +*** + +### Default format for American English ("en-US") + +This example will convert a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset) to the default format for American English `"en-US"` (i.e. `"MM/d/yyyy h:m:s tt zzz"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting a Date Time representing midnight on 31st December 2021 (with a `0` UTC time offset and without a format template), but specifying an American English `"en-US"` text representation, will result in the variable `($)Text` being updated to the following: + +```json +"12/31/2021 12:00:00 AM +00:00" +``` + +*** + +### Full Date Long Time format for American English ("en-US") + +This example will convert a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset) to the Full Date Long Time format for American English `"en-US"` (i.e. `"dddd, MMMM d, yyyy h:m:s tt"`). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"F"` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting a Date Time representing midnight on 31st December 2021 (with a `0` UTC time offset), and specifying the Full Date Long Time format for American English `"en-US"`, will result in the variable `($)Text` being updated to the following: + +```json +"Friday, December 31, 2021 12:00:00 AM" +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to convert to [Text][Text Property]. + +By default, if no [Format Template][FormatTemplate Property] or [Format Provider][FormatProvider Property] are specified, the resultant [Text][Text Property] will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Format Template + +[Format Template][FormatTemplate Property] can be specified to define the format the [Date Time][DateTime Property] should be converted to (e.g. `"dd/MM/yyyy"` -> `"31/12/2021"`). + +If [Format Template][FormatTemplate Property] contains valid format specifiers (e.g. `"dd"` for 2 digit day representation), they will be subsitituted based on the [Date Time][DateTime Property]; characters that are not format specifiers will be passed through as literal text. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), the default format template of the specified [Format Provider][FormatProvider Property] is used. If [Format Provider][FormatProvider Property] is also not specified or `null` the [ISO 8601 Standard][] format will be used (i.e. `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`). + +For information about format templates and specifiers, please see [Date and Time Formatting][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `yyyy-MM-ddTHH:mm:ss.fffffffzzz` | + +### Format Provider + +[Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting.). + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IFormatProvider][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +### Text + +The [Text][Text Property] representation of the [Date Time][DateTime Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [FormatException][] | Thrown when [Format Template][FormatTemplate Property] is a single invalid format specifier (i.e. `"a"`). | + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +### Format Template and Specifiers + +Please note that changes to operating system date and time formats, could result in some of the examples above displaying different results. + +For information about format templates and specifiers, please see [Date and Time Formatting][]. + +### Null or Empty Format Template + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), the default format template of the specified [Format Provider][FormatProvider Property] is used. If [Format Provider][FormatProvider Property] is also not specified or `null` the [ISO 8601 Standard][] format will be used (i.e. `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`). + +### Null Format Provider + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +[DateTime Property]: {{< ref "#date-time" >}} +[FormatTemplate Property]: {{< ref "#format-template" >}} +[FormatProvider Property]: {{< ref "#format-provider" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[FormatException]: {{< url path="MSDocs.DotNet.Api.System.FormatException" >}} + +[Date and Time Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.MainDoc" >}} +[Invariant Culture rules]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.InvariantCulture" >}} +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[IFormatProvider]: {{< url path="Cortex.Reference.DataTypes.Text.IFormatProvider.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/convert-date-time/convert-text-to-date-time-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/convert-date-time/convert-text-to-date-time-block.md new file mode 100644 index 000000000..274d24ec8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/convert-date-time/convert-text-to-date-time-block.md @@ -0,0 +1,270 @@ +--- +title: "Convert Text To Date Time" +linkTitle: "Convert Text To Date Time" +description: "Converts Text to a Date Time." +--- + +{{< figure src="/blocks/date-and-time-convert-to-datetime-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTimeBlock)
+ +## Description + +Converts [Text][Text Property] to a [Date Time][DateTime Property]. + +Additional options can be specified: + +* [Format Template][FormatTemplate Property] can be specified to explicity define the format of the [Text][Text Property] (e.g. `"dd/MM/yyyy"`). +* [Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the conversion (e.g. `new CultureInfo("en-US")` will apply American English rules to the conversion). + +## Examples + +### ISO 8601 Standard Format + +[ISO 8601 Standard][] format is `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`. + +This example will convert `"2021-12-31T00:00:00.0000000+00:00"` to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"2021-12-31T00:00:00+00:00"` | `($)Text` is a variable of type [String][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `null` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Converting `"2021-12-31T00:00:00.0000000+00:00"` to a Date Time (without specifying any format template or provider) will result in the variable `($)DateTime` being updated to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +### Default format for Invariant Culture + +Default format for Invariant Culture is `"MM/dd/yyyy HH:mm:ss zzz"`. + +This example will convert `"12/31/2021 00:00:00 +00:00"` to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"12/31/2021 00:00:00 +00:00"` | `($)Text` is a variable of type [String][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `CultureInfo.InvariantCulture` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Converting `"12/31/2021 00:00:00 +00:00"` to a Date Time without specifying a format template but specifying Invariant Culture, will result in the variable `($)DateTime` being updated to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +### Full Date Long Time format for Invariant Culture + +Full Date Long Time format for Invariant Culture is `"dddd, dd MMMM yyyy HH:mm:ss"`. + +This example will convert `"Friday, 31 December 2021 00:00:00"` to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"Friday, 31 December 2021 00:00:00"` | `($)Text` is a variable of type [String][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"F"` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `CultureInfo.InvariantCulture` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Converting `"Friday, 31 December 2021 00:00:00"` to a Date Time specifying the Full Date Long Time format for Invariant Culture, will result in the variable `($)DateTime` being updated to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +### Default format for American English ("en-US") + +Default format for American English ("en-US") is `"MM/d/yyyy h:m:s tt zzz"`. + +This example will convert `"12/31/2021 12:00:00 AM +00:00"` to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"12/31/2021 12:00:00 AM +00:00"` | `($)Text` is a variable of type [String][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `null` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Converting `"12/31/2021 12:00:00 AM +00:00"` to a Date Time without specifying a format template but specifying American English `"en-US"`, will result in the variable `($)DateTime` being updated to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +### Full Date Long Time format for American English ("en-US") + +Full Date Long Time format for American English ("en-US") is `"dddd, MMMM d, yyyy h:m:s tt"`. + +This example will convert `"Friday, December 31, 2021 12:00:00 AM"` to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"Friday, December 31, 2021 12:00:00 AM"` | `($)Text` is a variable of type [String][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"F"` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Converting `"Friday, December 31, 2021 12:00:00 AM"` to a Date Time specifying the Full Date Long Time format for American English `"en-US"`, will result in the variable `($)DateTime` being updated to a Date Time representing midnight on 31st December 2021 (with `0` UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00.0000000+00:00" +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to convert to a [Date Time][DateTime Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Format Template + +[Format Template][FormatTemplate Property] can be specified to define the format the [Text][Text Property] is in (e.g. `"dd/MM/yyyy"`). + +If [Format Template][FormatTemplate Property] does not contain any valid format specifiers (e.g. `"ww/ww/wwww"`) and the text exactly matches the [Format Template][FormatTemplate Property] (e.g. `"ww/ww/wwww"`), then [Date Time][DateTime Property] is set to a [DateTimeOffset][] value that represents the current Date and Time. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), the [ISO 8601 Standard][] format will be used for the conversion (i.e. `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`). + +If the [ISO 8601 Standard][] format fails, then the default template of the specified [Format Provider][FormatProvider Property] will be used; if there is no specified [Format Provider][FormatProvider Property], then [Invariant Culture rules][] will be used instead. + +For information about format templates and specifiers, please see [Date and Time Formatting][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `yyyy-MM-ddTHH:mm:ss.fffffffzzz` | + +### Format Provider + +[Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the conversion (e.g. `new CultureInfo("en-US")` will apply American English rules to the conversion). + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IFormatProvider][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +### Date Time + +The [Date Time][DateTime Property] that has been converted from [Text][Text Property]. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [FormatException][] | Thrown when [Format Template][FormatTemplate Property] does not contain any valid specifiers (e.g. `"ww/ww/wwww"`). | +| | Thrown when [Format Template][FormatTemplate Property] contains non-specifier characters, and [Text][Text Property] does not match the characters exactly (e.g. `"01/10/2021 12:00"` and `"dd/ww/yyyy hh:mm"` will throw, but `"01/ww/2021 12:00"` and `"dd/ww/yyyy hh:mm"` does not). | +| | Thrown when [Format Template][FormatTemplate Property] is `null` or empty (i.e. `""`) and the [Text][Text Property] does not match the [ISO 8601 Standard][] format, the default format of the [Format Provider][FormatProvider Property] (e.g. `"31/12/2021 00:00"` and `"dd/MM/yyyy"`). | +| [PropertyEmptyException][] | Thrown when [Text][Text Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Text][Text Property] is `null`. | + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +### Format Template and Specifiers + +Please note that changes to operating system date and time formats, could result in some of the examples above displaying different results. + +For information about format templates and specifiers, please see [Date and Time Formatting][]. + +### Null or Empty Format Template + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), the [ISO 8601 Standard][] format will be used for the conversion (i.e. `"yyyy-MM-ddTHH:mm:ss.fffffffzzz"`). + +If the [ISO 8601 Standard][] format fails, then the default template of the specified [Format Provider][FormatProvider Property] will be used; if there is no specified [Format Provider][FormatProvider Property], then [Invariant Culture rules][] will be used instead. + +### Null Format Provider + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +[DateTime Property]: {{< ref "#date-time" >}} +[FormatTemplate Property]: {{< ref "#format-template" >}} +[FormatProvider Property]: {{< ref "#format-provider" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[FormatException]: {{< url path="MSDocs.DotNet.Api.System.FormatException" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[Date and Time Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.MainDoc" >}} +[Invariant Culture rules]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.InvariantCulture" >}} +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[IFormatProvider]: {{< url path="Cortex.Reference.DataTypes.Text.IFormatProvider.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/_index.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/_index.md new file mode 100644 index 000000000..fa05212da --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Date Time" +linkTitle: "Get Date Time" +description: "Get the current date time or parts of a date time (i.e. Year, Month, Day)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-current-date-time-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-current-date-time-block.md new file mode 100644 index 000000000..224868887 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-current-date-time-block.md @@ -0,0 +1,80 @@ +--- +title: "Get Current Date Time" +linkTitle: "Get Current Date Time" +description: "Gets the current Date Time." +--- + +{{< figure src="/blocks/date-and-time-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.GetDateTime.GetCurrentDateTimeBlock)
+ +## Description + +Gets the current [Date Time][DateTime Property]. + +## Examples + +### Get the current Date Time + +This example will get the current Date Time. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with no value | `($)DateTime` is a variable that will be set to a [DateTimeOffset][] value | + +#### Result + +Getting the current Date Time will result in the variable `($)DateTime` being set to a [DateTimeOffset][] representing the current Date Time (including a UTC time offset). Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-11-05T08:48:08.0307614+00:00" +``` + +*** + +## Properties + +### Date Time + +The current [Date Time][DateTime Property] including a UTC time offset. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +[DateTime Property]: {{< ref "#date-time" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-date-time-component-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-date-time-component-block.md new file mode 100644 index 000000000..7798a87e5 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-date-time/get-date-time-component-block.md @@ -0,0 +1,426 @@ +--- +title: "Get Date Time Component" +linkTitle: "Get Date Time Component" +description: "Gets a component (e.g. Year, Month, Day) of a specified Date Time." +--- + +{{< figure src="/blocks/date-and-time-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.GetDateTime.GetDateTimeComponentBlock)
+ +## Description + +Gets a [Component][Component Property] (e.g. Year, Month, Day) of the specified [Date Time][DateTime Property]. + +[Component Type][ComponentType Property] is used to specify which type of component to get. + +For more information about values that can be specified for [Component Type][ComponentType Property], please see [DateTimeComponentType][] or the [examples][] below. + +## Examples + +### LocalDateTime + +This example will get the LocalDateTime of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +In this example assume that the local date and time is in the GMT time zone. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T00:05:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.LocalDateTime` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the LocalDateTime (GMT) of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to a [DateTime][] value. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T10:00:00+00:00" +``` + +*** + +### UtcDateTime + +This example will get the UTCDateTime of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.UtcDateTime` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the UTCDateTime of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to a [DateTime][] value. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T10:00:00Z" +``` + +*** + +### Date + +This example will get the Date component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Date` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Date component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to a [DateTime][] value. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-12-31T00:00:00" +``` + +*** + +### Time + +This example will get the Time component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Time` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Time component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [TimePeriod][] value: + +```json +{ + "Years": 0, + "Months": 0, + "Days": 0, + "Hours": 5, + "Minutes": 0, + "Seconds": 0, + "Milliseconds": 0 +} +``` + +### Year + +This example will get the Year component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Year` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Year component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +2021 +``` + +*** + +### Month + +This example will get the Month component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Month` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Month component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +12 +``` + +### Day + +This example will get the Day component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Day` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Day component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +31 +``` + +### Hour + +This example will get the Hour component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Hour` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Hour component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +5 +``` + +*** + +### Minute + +This example will get the Minute component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Minute` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Minute component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +0 +``` + +*** + +### Second + +This example will get the Second component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Second` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Second component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +0 +``` + +*** + +### Millisecond + +This example will get the Millisecond component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Millisecond` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Millisecond component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +0 +``` + +*** + +### Offset + +This example will get the Offset component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.Offset` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the Offset component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [TimeSpan][] value with the following text representation: + +```json +"-5:00:00" +``` + +*** + +### DayOfYear + +This example will get the DayOfYear component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.DayOfYear` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the DayOfYear component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [Int32][] value: + +```json +365 +``` + +*** + +### DayOfWeek + +This example will get the DayOfWeek component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset). + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-12-31T05:00:00-05:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Component Type][ComponentType Property] | `($)ComponentType`, with value of `DateTimeComponentType.DayOfWeek` | `($)DateTime` is a variable of type [DateTimeComponentType][] | +| [Component][Component Property] | `($)Component`, with no value | `($)Component` is a variable that will be set to a [dynamic][] value | + +#### Result + +Getting the DayOfWeek component of a Date Time representing 5am on 31st December 2021 (with `-5` UTC time offset), will result in the variable `($)Component` being updated to the following [DayOfWeek][] value: + +```json +DayOfWeek.Friday +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to get the specified [Component Type][ComponentType Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Component Type + +The [Component Type][ComponentType Property] to get from the [Date Time][DateTime Property]. + +For more information about values that can be specified for [Component Type][ComponentType Property], please see [DateTimeComponentType][] or the [examples][] above. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeComponentType][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `LocalDateTime` | + +### Component + +The [Component][Component Property] from the [Date Time][DateTime Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Component` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Component Type][ComponentType Property] is not one of the specified [DateTimeComponentType][] types (e.g. `(DateTimeComponentType)100`). | + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +### Why does the Component property return a dynamic data type? + +The decision for [Component][Component Property] to return a [dynamic data type][dynamic] rather than an [Object][], was to avoid users having to [cast][Object Casting] the component to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Component][Component Property] (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue. + +If it is desirable to have any issues reported as messages when trying to debug the flow, the user can [cast][Object Casting] the variable specified for [Component][Component Property] to its correct type when using it (e.g. for UtcDateTime component it could be case as follows: `(DateTime)($)Component`). + +[DateTime Property]: {{< ref "#date-time" >}} +[ComponentType Property]: {{< ref "#component-type" >}} +[Component Property]: {{< ref "#component" >}} +[Examples]: {{< ref "#examples" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[DateTime]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTime.MainDoc" >}} +[DateTimeComponentType]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeComponentType.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} +[TimeSpan]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimeSpan.MainDoc" >}} +[DayOfWeek]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DayOfWeek.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/_index.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/_index.md new file mode 100644 index 000000000..631288791 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Time Period" +linkTitle: "Get Time Period" +description: "Get the time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) between two date times." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/get-time-period-between-date-times-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/get-time-period-between-date-times-block.md new file mode 100644 index 000000000..a99f13281 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/get-time-period/get-time-period-between-date-times-block.md @@ -0,0 +1,146 @@ +--- +title: "Get Time Period Between Date Times" +linkTitle: "Get Time Period Between Date Times" +description: "Gets the Time Period between two Date Times." +--- + +{{< figure src="/blocks/date-and-time-get-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.GetTimePeriod.GetTimePeriodBetweenDateTimesBlock)
+ +## Description + +Get the [Time Period][TimePeriod Property] between the specified [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property]. + +## Examples + +### Get Time Period between Start Date Time and End Date Time + +This example will get the Time Period between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Start Date Time][StartDateTime Property] | `($)StartDateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)StartDateTime` is a variable of type [DateTimeOffset][] | +| [End Date Time][EndDateTime Property] | `($)EndDateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)EndDateTime` is a variable of type [DateTimeOffset][] | +| [Time Period][TimePeriod Property] | `($)TimePeriod`, with no value | `($)TimePeriod` is a variable that will be set to a [TimePeriod][] value | + +#### Result + +Getting the Time Period between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00` will result in the variable `($)TimePeriod` being updated to the following: + +```json +{ + "Years": 0, + "Months": 0, + "Days": 365, + "Hours": 0, + "Minutes": 0, + "Seconds": 0, + "Milliseconds": 0 +} +``` + +*** + +## Properties + +### Start Date Time + +The [Start Date Time][StartDateTime Property] to get the Time Period between. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)StartDateTime` with no value | + +### End Date Time + +The [End Date Time][EndDateTime Property] to get the Time Period between. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)EndDateTime` with no value | + +### Time Period + +The [Time Period][TimePeriod Property] between the [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property]. + +[Time Period][TimePeriod Property] can have positive and negative components where components are: + +* Years +* Months +* Days +* Hours +* Minutes +* Seconds +* Milliseconds + +In this block, the Year and Month components are not used as they aren't constant (i.e. Years can have different numbers of days depending upon whether it is a leap year or not, and months can have different numbers of days); instead Days will be used. + +[Time Period][TimePeriod Property] is calculated by subtracting [Start Date Time][StartDateTime Property] from [End Date Time][EndDateTime Property]; therefore if [Start Date Time][StartDateTime Property] is less than [End Date Time][EndDateTime Property], the [Time Period][TimePeriod Property] components will be positive, if it is equal they will be `0` and finally if it is greater than they will be negative. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TimePeriod][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TimePeriod` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +### Years and Months components not used + +In this block, the Year and Month components are not used as they aren't constant (i.e. Years can have different numbers of days depending upon whether it is a leap year or not, and months can have different numbers of days); instead Days will be used. + +### Start Date Time greater than End Date Time + +[Start Date Time][StartDateTime Property] can be greater than [End Date Time][EndDateTime Property]; if this is the case the components of the [Time Period][TimePeriod Property] will be negative. + +[StartDateTime Property]: {{< ref "#start-date-time" >}} +[EndDateTime Property]: {{< ref "#end-date-time" >}} +[TimePeriod Property]: {{< ref "#time-period" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/_index.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/_index.md new file mode 100644 index 000000000..0bc30351e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/_index.md @@ -0,0 +1,5 @@ +--- +title: "Is Date Time" +linkTitle: "Is Date Time" +description: "Check if a date time is equal to another date time, before it, after it, or between two date times." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-after-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-after-block.md new file mode 100644 index 000000000..16c57e6d5 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-after-block.md @@ -0,0 +1,156 @@ +--- +title: "Is Date Time After" +linkTitle: "Is Date Time After" +description: "Checks if a Date Time is after another Date Time." +--- + +{{< figure src="/blocks/date-and-time-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeAfterBlock)
+ +## Description + +Checks if a [Date Time][DateTime Property] is after a given [Date Time To Compare][DateTimeToCompare Property]. + +## Examples + +### Date Time is after Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is after `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is After][DateTimeIsAfter Property] | `($)DateTimeIsAfter`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is after `2021-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsAfter` being updated to the following: + +```json +true +``` + +*** + +### Date Time is before Date Time To Compare + +This example will check if `2021-01-01T00:00:00+00:00` is after `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is After][DateTimeIsAfter Property] | `($)DateTimeIsAfter`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2021-01-01T00:00:00+00:00` is after `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsAfter` being updated to the following: + +```json +false +``` + +*** + +### Date Time is equal to Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is after `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is After][DateTimeIsAfter Property] | `($)DateTimeIsAfter`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is after `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsAfter` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to check is after [Date Time To Compare][DateTimeToCompare Property]. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Date Time To Compare + +The Date Time to check if [Date Time][DateTime Property] is after. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeToCompare` with no value | + +### Date Time Is After + +The result of the is after check. + +If [Date Time][DateTime Property] is after [Date Time To Compare][DateTimeToCompare Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeIsAfter` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +[DateTime Property]: {{< ref "#date-time" >}} +[DateTimeToCompare Property]: {{< ref "#date-time-to-compare" >}} +[DateTimeIsAfter Property]: {{< ref "#date-time-is-after" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-before-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-before-block.md new file mode 100644 index 000000000..a427d81fa --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-before-block.md @@ -0,0 +1,156 @@ +--- +title: "Is Date Time Before" +linkTitle: "Is Date Time Before" +description: "Checks if a Date Time is before another Date Time." +--- + +{{< figure src="/blocks/date-and-time-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeBeforeBlock)
+ +## Description + +Checks if a [Date Time][DateTime Property] is before a given [Date Time To Compare][DateTimeToCompare Property]. + +## Examples + +### Date Time is before Date Time To Compare + +This example will check if `2021-01-01T00:00:00+00:00` is before `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Before][DateTimeIsBefore Property] | `($)DateTimeIsBefore`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2021-01-01T00:00:00+00:00` is before `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsBefore` being updated to the following: + +```json +true +``` + +*** + +### Date Time is after Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is before `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Before][DateTimeIsBefore Property] | `($)DateTimeIsBefore`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is before `2021-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsBefore` being updated to the following: + +```json +false +``` + +*** + +### Date Time is equal to Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is before `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Before][DateTimeIsBefore Property] | `($)DateTimeIsBefore`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is before `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsBefore` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to check is before [Date Time To Compare][DateTimeToCompare Property]. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Date Time To Compare + +The Date Time to check if [Date Time][DateTime Property] is before. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeToCompare` with no value | + +### Date Time Is Before + +The result of the is before check. + +If [Date Time][DateTime Property] is before [Date Time To Compare][DateTimeToCompare Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeIsBefore` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +[DateTime Property]: {{< ref "#date-time" >}} +[DateTimeToCompare Property]: {{< ref "#date-time-to-compare" >}} +[DateTimeIsBefore Property]: {{< ref "#date-time-is-before" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-between-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-between-block.md new file mode 100644 index 000000000..742231db0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-between-block.md @@ -0,0 +1,161 @@ +--- +title: "Is Date Time Between" +linkTitle: "Is Date Time Between" +description: "Checks if a Date Time is between two Date Times." +--- + +{{< figure src="/blocks/date-and-time-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeBetweenBlock)
+ +## Description + +Checks if a [Date Time][DateTime Property] is between the specified [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property]. + +## Examples + +### Date Time is between Start Date Time and End Date Time + +This example will check if `2021-06-01T00:00:00+00:00` is between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-06-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Start Date Time][StartDateTime Property] | `($)StartDateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)StartDateTime` is a variable of type [DateTimeOffset][] | +| [End Date Time][EndDateTime Property] | `($)EndDateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)EndDateTime` is a variable of type [DateTimeOffset][] | +| [Date Time Is Between][DateTimeIsBetween Property] | `($)DateTimeIsBetween`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2021-06-01T00:00:00+00:00` is between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsBetween` being updated to the following: + +```json +true +``` + +*** + +### Date Time is not between Start Date Time and End Date Time + +This example will check if `2020-01-01T00:00:00+00:00` is between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2020-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Start Date Time][StartDateTime Property] | `($)StartDateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)StartDateTime` is a variable of type [DateTimeOffset][] | +| [End Date Time][EndDateTime Property] | `($)EndDateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)EndDateTime` is a variable of type [DateTimeOffset][] | +| [Date Time Is Between][DateTimeIsBetween Property] | `($)DateTimeIsBetween`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2020-01-01T00:00:00+00:00` is between `2021-01-01T00:00:00+00:00` and `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsBetween` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to check is between [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property]. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Start Date Time + +The [Start Date Time][StartDateTime Property] to check against. This is inclusive, which means if [Date Time][DateTime Property] is equal to it, it will be considered between. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)StartDateTime` no value | + +### End Date Time + +The [End Date Time][EndDateTime Property] to check against. This is inclusive, which means if [Date Time][DateTime Property] is equal to it, it will be considered between. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)EndDateTime` with no value | + +### Date Time Is Between + +The result of the is between check. + +If [Date Time][DateTime Property] is between (and including) the [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeIsBetween` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +### Start Date Time and End Date Time are inclusive + +The [Start Date Time][StartDateTime Property] and [End Date Time][EndDateTime Property] properties are both inclusive, which means if [Date Time][DateTime Property] is equal to either of them, it will be considered between. + +### Start Date Time greater than End Date Time + +[Start Date Time][StartDateTime Property] can be greater than [End Date Time][EndDateTime Property]; as long as [Date Time][DateTime Property] is between or equal to either of them the variable specified for [Date Time Is Between][DateTimeIsBetween Property] will be set to `true`, otherwise it will be set to `false`. + +[DateTime Property]: {{< ref "#date-time" >}} +[StartDateTime Property]: {{< ref "#start-date-time" >}} +[EndDateTime Property]: {{< ref "#end-date-time" >}} +[DateTimeIsBetween Property]: {{< ref "#date-time-is-between" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-equal-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-equal-block.md new file mode 100644 index 000000000..2d885a61c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-equal-block.md @@ -0,0 +1,156 @@ +--- +title: "Is Date Time Equal" +linkTitle: "Is Date Time Equal" +description: "Checks if a Date Time is equal to another Date Time." +--- + +{{< figure src="/blocks/date-and-time-is-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeEqualBlock)
+ +## Description + +Checks if a [Date Time][DateTime Property] is equal to a given [Date Time To Compare][DateTimeToCompare Property]. + +## Examples + +### Date Time is equal to Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is equal to `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Equal][DateTimeIsEqual Property] | `($)DateTimeIsEqual`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is equal `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsEqual` being updated to the following: + +```json +true +``` + +*** + +### Date Time is after Date Time To Compare + +This example will check if `2022-01-01T00:00:00+00:00` is equal to `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Equal][DateTimeIsEqual Property] | `($)DateTimeIsEqual`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2022-01-01T00:00:00+00:00` is equal to `2021-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsEqual` being updated to the following: + +```json +false +``` + +*** + +### Date Time is before Date Time To Compare + +This example will check if `2021-01-01T00:00:00+00:00` is equal to `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Date Time To Compare][DateTimeToCompare Property] | `($)DateTimeToCompare`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTimeToCompare` is a variable of type [DateTimeOffset][] | +| [Date Time Is Equal][DateTimeIsEqual Property] | `($)DateTimeIsEqual`, with no value | `($)DateTime` is a variable that will be set to a [Boolean][] value | + +#### Result + +Checking if `2021-01-01T00:00:00+00:00` is equal to `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTimeIsEqual` being updated to the following: + +```json +false +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to check is equal to [Date Time To Compare][DateTimeToCompare Property]. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Date Time To Compare + +The Date Time to check if [Date Time][DateTime Property] is equal to. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeToCompare` with no value | + +### Date Time Is Equal + +The result of the is equal check. + +If [Date Time][DateTime Property] is equal to [Date Time To Compare][DateTimeToCompare Property], the specified variable will be set to `true`, otherwise it will be set to `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTimeIsEqual` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Dates and Time + +The default text representation of Date and Time will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information, please see [Working with Date and Time][]. + +[DateTime Property]: {{< ref "#date-time" >}} +[DateTimeToCompare Property]: {{< ref "#date-time-to-compare" >}} +[DateTimeIsEqual Property]: {{< ref "#date-time-is-equal" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/_index.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/_index.md new file mode 100644 index 000000000..95e6ebff1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/_index.md @@ -0,0 +1,5 @@ +--- +title: "Subtract Time Period" +linkTitle: "Subtract Time Period" +description: "Subtract a time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) from a date time." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/subtract-time-period-block.md b/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/subtract-time-period-block.md new file mode 100644 index 000000000..9a0ddbd83 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/date-and-time/subtract-time-period/subtract-time-period-block.md @@ -0,0 +1,157 @@ +--- +title: "Subtract Time Period" +linkTitle: "Subtract Time Period" +description: "Subtracts a Time Period to from specified Date Time." +--- + +{{< figure src="/blocks/date-and-time-subtract-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.DateAndTime.SubtractTimePeriod.SubtractTimePeriodBlock)
+ +## Description + +Subtracts a [Time Period][TimePeriod Property] from the specified [Date Time][DateTime Property]. + +This block can subtract both positive and negative [TimePeriod][] values. + +## Examples + +### Subtract a positive Time Period + +This example will subtract `1 year` from `2022-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2022-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Time Period][TimePeriod Property] | `($)TimePeriod`, with value of `{"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}` | `($)TimePeriod` is a variable of type [TimePeriod][] | + +#### Result + +Subtracting `1 year` from `2022-01-01T00:00:00+00:00` will result in the variable `($)DateTime` being updated. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2021-01-01T00:00:00+00:00" +``` + +*** + +### Subtract a negative Time Period + +This example will subtract `-1 year` from `2021-01-01T00:00:00+00:00`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Date Time][DateTime Property] | `($)DateTime`, with value of [DateTimeOffset][] that has a text representation of `2021-01-01T00:00:00+00:00` | `($)DateTime` is a variable of type [DateTimeOffset][] | +| [Time Period][TimePeriod Property] | `($)TimePeriod`, with value of `{"Years": -1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}` | `($)TimePeriod` is a variable of type [TimePeriod][] | + +#### Result + +Subtracting `-1 year` from `2021-01-01T00:00:00+00:00` will result in `1 year` being added and the variable `($)DateTime` being updated. Its text representation will be in the [ISO 8601 Standard][], which can be seen below: + +```json +"2022-01-01T00:00:00+00:00" +``` + +*** + +## Properties + +### Date Time + +The [Date Time][DateTime Property] to subtract the [Time Period][TimePeriod Property] from. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [DateTimeOffset][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)DateTime` with no value | + +### Time Period + +The [Time Period][TimePeriod Property] to subtract from the [Date Time][DateTime Property]. + +[Time Period][TimePeriod Property] can have positive and negative components where components are: + +* Years +* Months +* Days +* Hours +* Minutes +* Seconds +* Milliseconds + +When subtracting a [Time Period][TimePeriod Property], the block will first subtract years, followed by months, days, hours, minutes, seconds and finally milliseconds. + +When subtracting months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. subtracting one month from `2021-02-28T23:59:59+00:00` will equate to `2021-01-31T23:59:59+00:00`). + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TimePeriod][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | Years: `0`(Cortex.Blocks.Decisions.If.IfNullExitBottomBlock`1)
+ +## Description + +Checks if a given [Value][Value Property] is `null`; if so the flow execution exits via the block's bottom port (green tick), otherwise it exits via the right port (red cross). + +For information about `null`, please see [Null and Nullable Types][]. + +## Examples + +### Value is null + +This example will check if `null` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `null` | `($)Value` is a variable of type [String][] | + +#### Result + +`null` is `null`, so the flow execution exits via the block's bottom port (green tick). + +*** + +### Value is not null + +This example will check if `"The quick brown fox jumps over the lazy dog"` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Value` is a variable of type [String][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not `null`, so the flow execution exits via the block's right port (red cross). + +*** + +## Properties + +### Value + +The [Value][Value Property] to check is `null`. + +For information about `null`, please see [Null and Nullable Types][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TValue][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | No value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNotNullableException][] | Thrown when [Value][Value Property] is given a non-nullable value type. | + +## Remarks + +### Null and Nullable Types + +For information about `null`, please see [Null and Nullable Types][]. + +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[TValue]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[Null and Nullable Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.NullAndNullableTypes.MainDoc" >}} + +[PropertyNotNullableException]: {{< url path="Cortex.Reference.Exceptions.Decisions.PropertyNotNullableException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-null-exit-right-block-1.md b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-null-exit-right-block-1.md new file mode 100644 index 000000000..1404dab06 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-null-exit-right-block-1.md @@ -0,0 +1,96 @@ +--- +title: "If Null Exit Right" +linkTitle: "If Null Exit Right" +description: "Checks if a given value is `null`; if so the flow execution exits via the block's right port, otherwise it exits via the bottom port." +--- + +{{< figure src="/blocks/decisions-if-true-exit-right-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Decisions.If.IfNullExitRightBlock`1)
+ +## Description + +Checks if a given [Value][Value Property] is `null`; if so the flow execution exits via the block's right port (green tick), otherwise it exits via the bottom port (red cross). + +For information about `null`, please see [Null and Nullable Types][]. + +## Examples + +### Value is null + +This example will check if `null` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `null` | `($)Value` is a variable of type [String][] | + +#### Result + +`null` is `null`, so the flow execution exits via the block's right port (green tick). + +*** + +### Value is not null + +This example will check if `"The quick brown fox jumps over the lazy dog"` is `null`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Value` is a variable of type [String][] | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` is not `null`, so the flow execution exits via the block's bottom port (red cross). + +*** + +## Properties + +### Value + +The [Value][Value Property] to check is `null`. + +For information about `null`, please see [Null and Nullable Types][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TValue][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | No value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNotNullableException][] | Thrown when [Value][Value Property] is given a non-nullable value type. | + +## Remarks + +### Null and Nullable Types + +For information about `null`, please see [Null and Nullable Types][]. + +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[TValue]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[Null and Nullable Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.NullAndNullableTypes.MainDoc" >}} + +[PropertyNotNullableException]: {{< url path="Cortex.Reference.Exceptions.Decisions.PropertyNotNullableException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-bottom-block.md b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-bottom-block.md new file mode 100644 index 000000000..2fa2222e2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-bottom-block.md @@ -0,0 +1,81 @@ +--- +title: "If True Exit Bottom" +linkTitle: "If True Exit Bottom" +description: "Checks if a given value evaluates to `true`; if so the flow execution exits via the block's bottom port, otherwise it exits via the right port." +--- + +{{< figure src="/blocks/decisions-if-true-exit-bottom-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Decisions.If.IfTrueExitBottomBlock)
+ +## Description + +Checks if a given [Value][Value Property] evaluates to `true`; if so the flow execution exits via the block's bottom port (green tick), otherwise it exits via the right port (red cross). + +## Examples + +### Value is true + +This example will check if `1 + 1 == 2` evaluates to `true` or `false`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `1 + 1 == 2` | `($)Value` is a variable whose value evaluates to type [Boolean][] | + +#### Result + +`1 + 1 == 2` is `true`, so the flow execution exits via the block's bottom port (green tick). + +*** + +### Value is false + +This example will check if `1 + 1 == 1` evaluates to `true` or `false`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `1 + 1 == 1` | `($)Value` is a variable whose value evaluates to type [Boolean][] | + +#### Result + +`1 + 1 == 1` is `false`, so the flow execution exits via the block's right port (red cross). + +*** + +## Properties + +### Value + +The [Value][Value Property] to check evaluates to `true` or `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | No value | + +## Exceptions + +None + +## Remarks + +No remarks for the block. + +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-right-block.md b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-right-block.md new file mode 100644 index 000000000..8937791eb --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/decisions/if/if-true-exit-right-block.md @@ -0,0 +1,81 @@ +--- +title: "If True Exit Right" +linkTitle: "If True Exit Right" +description: "Checks if a given value evaluates to `true`; if so the flow execution exits via the block's right port, otherwise it exits via the bottom port." +--- + +{{< figure src="/blocks/decisions-if-true-exit-right-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Decisions.If.IfTrueExitRightBlock)
+ +## Description + +Checks if a given [Value][Value Property] evaluates to `true`; if so the flow execution exits via the block's right port (green tick), otherwise it exits via the bottom port (red cross). + +## Examples + +### Value is true + +This example will check if `1 + 1 == 2` evaluates to `true` or `false`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `1 + 1 == 2` | `($)Value` is a variable whose value evaluates to type [Boolean][] | + +#### Result + +`1 + 1 == 2` is `true`, so the flow execution exits via the block's right port (green tick). + +*** + +### Value is false + +This example will check if `1 + 1 == 1` evaluates to `true` or `false`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | `($)Value`, with value `1 + 1 == 1` | `($)Value` is a variable whose value evaluates to type [Boolean][] | + +#### Result + +`1 + 1 == 1` is `false`, so the flow execution exits via the block's bottom port (red cross). + +*** + +## Properties + +### Value + +The [Value][Value Property] to check evaluates to `true` or `false`. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | No value | + +## Exceptions + +None + +## Remarks + +No remarks for the block. + +[Value Property]: {{< ref "#value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/email/_index.md b/content/en/docs/2023.9/Reference/Blocks/email/_index.md new file mode 100644 index 000000000..da41aa5a8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Email" +linkTitle: "Email" +description: "Blocks related to working with Emails." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/email/send-email/_index.md b/content/en/docs/2023.9/Reference/Blocks/email/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/email/send-email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Send Email" +linkTitle: "Send Email" +description: "Blocks related to sending Emails." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/email/send-email/send-email-using-smtp-server-block.md b/content/en/docs/2023.9/Reference/Blocks/email/send-email/send-email-using-smtp-server-block.md new file mode 100644 index 000000000..06b061508 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/email/send-email/send-email-using-smtp-server-block.md @@ -0,0 +1,581 @@ +--- +title: "Send Email Using SMTP Server" +linkTitle: "Send Email Using SMTP Server" +description: "Sends an email using the specified SMTP server." +--- + +{{< figure src="/blocks/email-send-email-using-smtp-server-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Email.SendEmail.SendEmailUsingSmtpServerBlock)
+ +## Description + +Connects to an [SMTP][] server using the specified [Basic Email Session Details][Basic Email Session Details Property], and sends an [Email Message][Email Message Property]. + +[Close Session][Close Session Property] can be specified to choose whether the connection to the [SMTP][] server is closed or is kept open for use on subsequent Send Email Using SMTP Server blocks. + +## Examples + +### Sending an email to a single recipient + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com`. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be to set to `true` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information about when [UseSsl][] should be set to `true` or `false`, see [Setting UseSsl][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Email Message][Email Message Property] | `($)EmailMessage` with value `{"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`Example paragraph text
" +``` + +[Outlook][] will display the email body as follows: + +{{< figure src="/images/send-email-using-smtp-server-html-email.png" >}} + +For more information on how the body of an email will be displayed, see the help provided by the respective email client. + +### Attachments + +Attachments can be sent in an email by providing a list of file paths in the [Attachments][] property of the [Email Message][Email Message Property]. For more information concerning attaching files to an email, see the sections below. + +#### Supported file path formats + +Each file path in the [Attachments][] within the [Email Message][Email Message Property] can be an: + +- Absolute file path +- Relative file path +- UNC file path + +where each file path must be accessible from the server executing the flow. + +For more information about each of these supported file path formats, please see [File & Folder Paths][]. + +#### File paths need escaping + +Each file path in the [Attachments][] within the [Email Message][Email Message Property] requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow. + +Escaping can be done in two ways: + +- Escaping the `\` character with another `\` character (e.g. `"C:\\Attachments\\attachment.txt"`), or +- Prepending an `@` character before the start of the File Path (e.g. `@"C:\Attachments\attachment.txt"`) + +#### Null file path + +If `null` is provided as a file path in the [Attachments][] within the [Email Message][Email Message Property], an [ArgumentNullException][] is thrown. + +#### Empty file path + +If an empty string is provided as a file path in the the [Attachments][] within the [Email Message][Email Message Property], an [ArgumentException][] is thrown. + +#### File path does not exist + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] does not exist, a [FileNotFoundException][] is thrown. + +#### Invalid file path + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] is invalid (i.e. contains any of the following characters: ", *, ?, |, <, >, :, \, /), an [IOException][] will be thrown. + +#### File path points to a folder + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] points to a folder, an [UnauthorizedAccessException][] will be thrown. + +#### File path contains leading spaces + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] contains leading spaces they are not removed and an [IOException][] will be thrown; however, trailing spaces are removed. + +#### File path contains only whitespace or the NUL character + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] contains only whitespace (i.e. `" "`) or the NUL character (i.e. `\0`), an [ArgumentException][] will be thrown. + +#### File path exceeds the system-defined maximum length + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] exceeds the system-defined maximum length (typically 32,767), a [PathTooLongException][] will be thrown. + +#### User does not have necessary permissions to attach the file + +If the user the flow is executing as does not have permissions to access the file at the provided file path in the [Attachments][] within the [Email Message][Email Message Property], an [UnauthorizedAccessException][] will be thrown. + +#### Attachment size limit + +The combined size of all the [Attachments][] within the [Email Message][Email Message Property] must be less than the limit specified by the email service provider. If the combined size of all of the attachments is greater than the limit, an [SmtpCommandException][] will be thrown. + +For [Outlook][] this is `20 MB` and for [Gmail][] this is `25 MB`, for more information on the size limits for other email service providers, see the help provided by the respective email service provider. + +### Supported formats for ServerDetails.Host + +The following formats are supported for [Host][] in [ServerDetails][]: + +- Fully Qualified Domain Name (e.g. `"smtp.gmail.com"`) +- Machine name (e.g. `"mail-server1"`) +- IP address (e.g. `"127.0.0.1"`) +- Localhost (e.g. `"localhost"`) + +### Setting UseSsl + +The [ServerDetails][] within the [Basic Email Session Details][Basic Email Session Details Property] specifies which [SMTP][] server to connect to. The value of the [UseSsl][] property inside this object depends on the [Host][] and [Port][] being connected to. There are two types of [SSL][]/[TLS][] connections that can occur: + +- [SSL][]/[TLS][] is used as soon as a connection is established +- [SSL][]/[TLS][] is used via the STARTTLS command if it is available + +The above two points correspond to the [UseSsl][] property being set to `true` and `false` respectively. As such, generally the following rules can be followed to determine whether [UseSsl][] should be set to `true` or `false`: + +- If the [Port][] being connected to is `465` then [UseSsl][] should be set to `true` +- If the [Port][] being connected to is `25` or `587` then [UseSsl][] should be set to `false` + +### Setting Credentials + +The [UserCredentials][] within the [Basic Email Session Details][Basic Email Session Details Property] specifies what user to connect as on the [SMTP][] server. The value of the [Username][] property may optionally be encrypted, however the [Password][] should be encrypted. For more information on how to encrypt the password, see [EncryptedText][]. + +Note that the [UserCredentials][] object also contains a [Domain][] property which is ignored by this block. + +### Opening Sessions + +The Send Email Using SMTP Server block automatically handles creating and opening sessions for the specified [Basic Email Session Details][Basic Email Session Details Property] using the following rules: + +- If a session does not exist, a new session will be created, opened and used when the block runs. +- If a session already exists but is closed, the session will be opened and used when the block runs. +- If a session already exists and is open, the session will be used when the block runs. + +[Basic Email Session Details][Basic Email Session Details Property] will keep the session open across multiple Send Email Using SMTP Server blocks as long as [Close Session][Close Session Property] is set to `false`. Keeping the session open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening sessions for each execution. + +Note that for all [SSL][] connections, the protocol to be used will be negotiated with the server depending on which protocols are available. Similarly, the [SASL][] mechanism to be used will be negotiated with the mail server based on the available mechanisms. + +For information on how to explicitly close a session, please see [Closing Sessions][]. + +### Closing Sessions + +Sessions can be explicitly closed by setting [Close Session][Close Session Property] to `true`. This causes the session to be closed after the [Email Message][Email Message Property] has been sent. + +If [Close Session][Close Session Property] is set to `false` the session will be closed when the [Variable][] that [Basic Email Session Details][Basic Email Session Details Property] is set to goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see [Variables][]. + +For information on how to open a session, please see [Opening Sessions][]. + +### Known Limitations + +Currently unauthenticated [SMTP][] servers are not supported. + +This limitation may be removed in the future. + +[Email Message Property]: {{< ref "#email-message" >}} +[Basic Email Session Details Property]: {{< ref "#basic-email-session-details" >}} +[Close Session Property]: {{< ref "#close-session" >}} + +[How does Priority affect sending an email?]: {{< ref "#how-does-priority-affect-sending-an-email" >}} +[How does BodyFormat affect sending an email?]: {{< ref "#how-does-bodyformat-affect-sending-an-email" >}} +[Setting UseSsl]: {{< ref "#setting-usessl" >}} +[Setting Credentials]: {{< ref "#setting-credentials" >}} +[Opening Sessions]: {{< ref "#opening-sessions" >}} +[Closing Sessions]: {{< ref "#closing-sessions" >}} +[Attachments Remarks]: {{< ref "#attachments" >}} +[Supported formats for ServerDetails.Host]: {{< ref "#supported-formats-for-serverdetailshost" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[EmailSessionException]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.MainDoc" >}} +[Invalid Port]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidPort" >}} +[Invalid Host]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidHost" >}} +[SSL Required]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslRequired" >}} +[SSL Unsupported]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslUnsupported" >}} +[Invalid User Credentials]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidUserCredentials" >}} +[creating an EmailMessage using a constructor]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.CreateAnEmailMessage" >}} + +[EmailSessionErrorCode Limitations]: {{< url path="Cortex.Reference.DataTypes.Email.EmailSessionErrorCode.Limitations" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} +[FileNotFoundException]: {{< url path="MSDocs.DotNet.Api.System.IO.FileNotFoundException" >}} +[IOException]: {{< url path="MSDocs.DotNet.Api.System.IO.IOException" >}} +[PathTooLongException]: {{< url path="MSDocs.DotNet.Api.System.IO.PathTooLongException" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} +[Property Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyIsInvalid">}} + +[SmtpCommandException]: {{< url path="MimeKit.Docs.SmtpCommandException" >}} +[UnauthorizedAccessException]: {{< url path="MSDocs.DotNet.Api.System.UnauthorizedAccessException" >}} + +[EmailMessage]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.MainDoc" >}} +[To]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.To" >}} +[From]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.From" >}} +[Cc]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Cc" >}} +[Bcc]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Bcc" >}} +[Priority]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Priority" >}} +[Subject]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Subject" >}} +[BodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.BodyFormat" >}} +[Body]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Body" >}} +[Attachments]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Attachments" >}} + +[EmailAddress]: {{< url path="Cortex.Reference.DataTypes.Email.EmailAddress.MainDoc" >}} +[Address]: {{< url path="Cortex.Reference.DataTypes.Email.EmailAddress.Address" >}} + +[EmailMessagePriority]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.MainDoc" >}} +[Normal]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.Normal" >}} +[Urgent]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.Urgent" >}} +[NonUrgent]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.NonUrgent" >}} + +[EmailMessageBodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.MainDoc" >}} +[HTML]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.HTML" >}} +[Text]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.Text" >}} + +[BasicEmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.MainDoc" >}} +[Credentials Property]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.Credentials" >}} +[ServerDetails Property]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.ServerDetails" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[Domain]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Domain" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[ServerDetails]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.MainDoc" >}} +[Host]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Host" >}} +[Port]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Port" >}} +[UseSsl]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.UseSsl" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[SASL]: {{< url path="Cortex.Reference.Glossary.P-T.SASL" >}} +[SMTP]: {{< url path="Cortex.Reference.Glossary.P-T.SMTP" >}} +[SSL]: {{< url path="Cortex.Reference.Glossary.P-T.SSL" >}} +[TLS]: {{< url path="Cortex.Reference.Glossary.P-T.TLS" >}} +[BCC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.BCC" >}} +[CC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.CC" >}} +[CRL]: {{< url path="Cortex.Reference.Glossary.A-E.CRL" >}} +[Gmail]: {{< url path="Cortex.Reference.Glossary.F-J.Gmail" >}} +[Outlook]: {{< url path="Cortex.Reference.Glossary.K-O.Outlook" >}} +[RFC 5321]: {{< url path="IETF.Email.RFC5321" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/_index.md b/content/en/docs/2023.9/Reference/Blocks/flows/_index.md new file mode 100644 index 000000000..3a64c9787 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/_index.md @@ -0,0 +1,5 @@ +--- +title: "Flows" +linkTitle: "Flows" +description: "Blocks related to executing Flows." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/_index.md b/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/_index.md new file mode 100644 index 000000000..df9410cb5 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/_index.md @@ -0,0 +1,5 @@ +--- +title: "End Flow" +linkTitle: "End Flow" +description: "Blocks that indicate the end of a flow." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/end-flow-block.md b/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/end-flow-block.md new file mode 100644 index 000000000..3abadcbc3 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/end-flow/end-flow-block.md @@ -0,0 +1,37 @@ +--- +title: "End Flow" +linkTitle: "End Flow" +description: "Indicates the end of a flow." +--- + +{{< figure src="/blocks/flows-end-flow-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Flows.EndFlow.EndFlowBlock)
+ +## Description + +Indicates the end of a flow; when a flow execution reaches this block, the execution is ended. + +A flow can contain any number of these blocks, and they can be placed anywhere in a flow. + +The block has no block specific properties, but it does have the `Description` property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. + +A breakpoint can be added to this block when debugging. + +## Examples + +No examples for the block. + +## Properties + +No properties for the block, other than the `Description` property that is common to all blocks. + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +None \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/_index.md b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/_index.md new file mode 100644 index 000000000..fb5ca15c1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/_index.md @@ -0,0 +1,5 @@ +--- +title: "Run Flow" +linkTitle: "Run Flow" +description: "Blocks that are used to run another flow." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-async-block.md b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-async-block.md new file mode 100644 index 000000000..c83489a80 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-async-block.md @@ -0,0 +1,272 @@ +--- +title: "Run Flow Async" +linkTitle: "Run Flow Async" +description: "Runs a chosen Flow asynchronously, returning a Task representing its execution." +--- + +{{< figure src="/blocks/flows-run-flow-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Flows.RunFlow.RunFlowAsyncBlock)
+ +## Description + +Runs a chosen [Flow][Flow Property] asynchronously using the [Inputs][Inputs Property] provided, returning an [IExecutionTask][] that represents the execution of the [Flow][Flow Property] in the [Execution Task][Execution Task Property] variable. + +## Examples + +### Running a Flow Asynchronously + +This example will run the [Flow][Flow Property] `add-database-entry` assigning the task representing the execution of the [Flow][Flow Property] to `($)ExecutionTask`. + +The [Flow][Flow Property] `add-database-entry` takes an [Input Variable][] `($)NewData`, which is then added to a database by the [Flow][Flow Property]. If no value is given for `($)NewData` the default value `DefaultNewDataValue` is used. The flow containing the [Run Flow Async][] block will then continue executing the rest of its blocks. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Flow][Flow Property] | [Flow][Flow Property], with value `add-database-entry` | [Flow][Flow Property] is of type [FlowReference][] | +| [Inputs][Inputs Property] | | [Inputs][Inputs Property] is of type [InputVariables][] | +| > NewData | `($)NewData`, with value `SomeNewDataToAddToDatabase` | `($)NewData` is of type [String][] | +| [Execution Task][Execution Task Property] | `($)ExecutionTask`, with no value | `($)ExecutionTask` is a variable of type [IExecutionTask][] | + +#### Result + +`SomeNewDataToAddToDatabase` is passed into the [Input Variable][] `($)NewData` for the [Flow][Flow Property] `add-database-entry`, which results in the [Flow][Flow Property] starting its execution. The flow containing the [Run Flow Async][] block continues executing without waiting for it to complete. + +After the [Flow][Flow Property] has started running, the [Execution Task][Execution Task Property] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} +``` + +Once the [Flow][Flow Property] has added the database entry and has completed successfully, the [Execution Task][Execution Task Property]'s properties will be updated to the following: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +### Running a Flow Asynchronously with Default Input Variables + +This example will run the [Flow][Flow Property] `add-database-entry` assigning the task representing the execution of the [Flow][Flow Property] to `($)ExecutionTask`. + +The [Flow][Flow Property] `add-database-entry` takes an [Input Variable][] `($)NewData`, which is then added to a database by the [Flow][Flow Property]. If no value is given for `($)NewData` the default value `DefaultNewDataValue` is used. The flow containing the [Run Flow Async][] block will then continue executing the rest of its blocks. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Flow][Flow Property] | [Flow][Flow Property], with value `add-database-entry` | [Flow][Flow Property] is of type [FlowReference][] | +| [Inputs][Inputs Property] | | [Inputs][Inputs Property] is of type [InputVariables][] | +| > NewData | No value (defaults to `DefaultNewDataValue`) | `($)NewData` is of type [String][] | +| [Execution Task][Execution Task Property] | `($)ExecutionTask`, with no value | `($)ExecutionTask` is a variable of type [IExecutionTask][] | + +#### Result + +As no value is passed into the [Input Variable][] `($)NewData` for the [Flow][Flow Property] `add-database-entry` the default of `DefaultNewDataValue` is used, which results in the [Flow][Flow Property] starting its execution. The flow containing the [Run Flow Async][] block continues executing without waiting for it to complete. + +After the [Flow][Flow Property] has started running, the [Execution Task][Execution Task Property] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} +``` + +Once the [Flow][Flow Property] has added the database entry and has completed successfully, the [Execution Task][Execution Task Property]'s properties will be updated to the following: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +## Properties + +### Flow + +The [Flow][Flow Property] that will be run. + +The [Literal Editor][] is the only editor available for this property, and it provides the developer a list of all available flows to choose from. + +| | | +|--------------------|---------------------------| +| Data Type | [FlowReference][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][Literal Editor] | +| Default Value | No value (defaults to `null`) | + +### Inputs + +The [Input Variables][Input Variable] that are passed to the [Flow][Flow Property] that will be run. + +It is recommended to use the [Literal Editor][] for this property as it detects and warns of changes to the Flow Contract, allowing users to [Sync the Editor][Syncing the Inputs Property with the Flow Contract]. + +| | | +|--------------------|---------------------------| +| Data Type | [InputVariables][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][Literal Editor] | +| Default Value | No initial value (Will be [synced][Syncing the Inputs Property with the Flow Contract] when the [Flow][Flow Property] is first [selected][Selecting a Flow]) | + +### Execution Task + +The [Execution Task][Execution Task Property] representing the asynchronous execution of the [Flow][Flow Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IExecutionTask][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][Variable Editor] | +| Default Value | `($)ExecutionTask` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|------|-------------| +| [InvalidInputVariablesException][] | Thrown when [Inputs][Inputs Property] is missing any [Input Variables][Input Variable] from the chosen [Flow][Flow Property]. See [Missing Input Variables][]. | +| | Thrown when [Inputs][Inputs Property] has any extra [Input Variables][Input Variable] that are not in the chosen [Flow][Flow Property]. See [Extra Input Variables][]. | +| | Thrown when [Inputs][Inputs Property] has any [Input Variables][Input Variable] that are not a valid type for [Input Variable][]. See [Input Variables of an Invalid Type][]. | + +## Remarks + +### Selecting a Flow + +{{< figure src="/images/run-flow-selecting-a-flow.gif" >}} + +A flow can be selected using the [Literal Editor][] on the [Flow Property][], a list of all available flows will be presented to the developer and can be searched by the Name or Id of a flow. + +When a [Flow][Flow Property] is selected the [Inputs Property][] will be [Synced with the Flow Contract][Syncing the Inputs Property with the Flow Contract]. + +### Default Values + +If an [Input Variable][] has a default value, then this default value will be used when running the [Flow][Flow Property] if the corresponding value in the [Inputs Property][] is left empty. See [Running a Flow with Default Input Variables][] for an example. + +Also, if an [Input Variable][] has a default value, and the corresponding value in the [Inputs Property][] is not of the same type, a [Validation Error][] will be raised when the flow is validated. + +For more information see [Input Variables][Input Variable]. + +### Parent Flow Ending Before Child Flow + +If the parent flow containing the [Run Flow Async][] block ends before the child [Flow][Flow Property], the child [Flow][Flow Property] will continue running to completion. + +### Exceptions Thrown by a Child Flow + +If the child [Flow][Flow Property] run by the [Run Flow Async][] block throws an exception that is unhandled then the exception is saved to the [Execution Task][Execution Task Property]. The parent flow containing the [Run Flow Async][] block will not pause when the exception is thrown unless the [Flow][Flow Property] is being waited on by a [Wait For][] block. + +See [Wait For Task][] block or [Wait For All Tasks][] block for more details. + +### Syncing the Inputs Property with the Flow Contract + +{{< figure src="/images/run-flow-contract-change.gif" >}} + +When a flow is first selected the [Inputs Property][] will be synced with the Flow Contract. + +When the contract of the flow changes (e.g. [Input Variables][Input Variable] of a called [Flow][Flow Property] are updated), a prompt will appear when the block is selected, allowing the user to sync the editor. + +This will cause: + +- Any missing [Input Variables][Input Variable] not present in the [Inputs Property][] to be added +- Any extra [Input Variables][Input Variable] present in the [Inputs Property][] to be removed +- Any [Input Variables][Input Variable] already present in the [Inputs Property][] to be retained + +[Undoing][] this action will cause the [Inputs Property][] to return to its previous state, from before it was synced, allowing any data to be retrieved from any extra [Input Variables][Input Variable]. + +### Known Limitations + +#### The Flow Property can only use the Literal Editor + +The Literal Editor is the only editor available for the [Flow Property][] + +In future this limitation may be removed. + +#### Syncing the Inputs Property with the Flow Contract is not available when using editors other than the Literal Editor + +[Syncing the Inputs Property with the Flow Contract][] is only available when the [Inputs Property][] uses the [Literal Editor][]. If any other editor is used, the prompt to sync will not be displayed and any changes will need to be resolved manually. + +[Flow Property]: {{< ref "#flow" >}} +[Inputs Property]: {{< ref "#inputs" >}} +[Outputs Property]: {{< ref "#outputs" >}} +[Execution Task Property]: {{< ref "#execution-task" >}} +[Syncing the Inputs Property with the Flow Contract]: {{< ref "#syncing-the-inputs-property-with-the-flow-contract" >}} +[Selecting a Flow]: {{< ref "#selecting-a-flow" >}} +[Running a Flow with Default Input Variables]: {{< ref "#running-a-flow-asynchronously-with-default-input-variables" >}} +[Default Values]: {{< ref "#default-values" >}} +[Exceptions Thrown by a Child Flow]: {{< ref "#exceptions-thrown-by-a-child-flow" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Literal Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Input Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} +[Output Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Validation Error]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.MainDoc" >}} + +[Undoing]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.Undo" >}} + +[FlowReference]: {{< url path="Cortex.Reference.DataTypes.Flows.FlowReference.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[InputVariables]: {{< url path="Cortex.Reference.DataTypes.Flows.InputVariables.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} + +[Run Flow Async]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} + +[Wait For]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.MainDoc" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.TaskHasThrown" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.GetSuccessfulResults" >}} + +[InvalidInputVariablesException]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.MainDoc" >}} +[Missing Input Variables]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.MissingInputVariables" >}} +[Extra Input Variables]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.ExtraInputVariables" >}} +[Input Variables of an Invalid Type]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.InputVariablesOfAnInvalidType" >}} + +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-block.md b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-block.md new file mode 100644 index 000000000..2c732076c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/run-flow/run-flow-block.md @@ -0,0 +1,246 @@ +--- +title: "Run Flow" +linkTitle: "Run Flow" +description: "Runs a chosen Flow, returning any output variables." +--- + +{{< figure src="/blocks/flows-run-flow-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Flows.RunFlow.RunFlowBlock)
+ +## Description + +Runs a chosen [Flow][Flow Property] using the [Inputs][Inputs Property] provided, returning any [Output Variables][Output Variable] from the [Flow][Flow Property] in the [Outputs][Outputs Property] variable. + +## Examples + +### Running a Flow + +This example will run the [Flow][Flow Property] `square-number-flow` saving the output variables to `($)Outputs`. + +The [Flow][Flow Property] `square-number-flow` takes an [Input Variable][] `($)NumberToSquare`, which is then multiplied by itself and saved to the [Output Variable][] `($)SquaredNumber`. If no value is given for `($)NumberToSquare` the default value `10` is used. The flow contains a block that checks that the [Input Variable][] `($)NumberToSquare` is larger than `0`, an exception is thrown by `square-number-flow` if `($)NumberToSquare` is not larger than `0`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Flow][Flow Property] | [Flow][Flow Property], with value `square-number-flow` | [Flow][Flow Property] is of type [FlowReference][] | +| [Inputs][Inputs Property] | | [Inputs][Inputs Property] is of type [InputVariables][] | +| > NumberToSquare | `($)NumberToSquare`, with value `5` | `($)NumberToSquare` is of type [Int32][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` is a variable of type [Structure][] | + +#### Result + +`5` is passed into the [Input Variable][] `($)NumberToSquare` for the [Flow][Flow Property] `square-number-flow`, which results in `25` being saved to the [Output Variable][] `($)SquaredNumber`. This results in the variable `($)Outputs` being updated to the following: + +```json +{ + "SquaredNumber": 25 +} +``` + +*** + +### Running a Flow with Default Input Variables + +This example will run the [Flow][Flow Property] `square-number-flow` saving the output variables to `($)Outputs`. + +The [Flow][Flow Property] `square-number-flow` takes an [Input Variable][] `($)NumberToSquare`, which is then multiplied by itself and saved to the [Output Variable][] `($)SquaredNumber`. If no value is given for `($)NumberToSquare` the default value `10` is used. The flow contains a block that checks that the [Input Variable][] `($)NumberToSquare` is larger than `0`, an exception is thrown by `square-number-flow` if `($)NumberToSquare` is not larger than `0`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Flow][Flow Property] | [Flow][Flow Property], with value `square-number-flow` | [Flow][Flow Property] is of type [FlowReference][] | +| [Inputs][Inputs Property] | | [Inputs][Inputs Property] is of type [InputVariables][] | +| > NumberToSquare | No value (defaults to `10`) | `NumberToSquare` is of type [Int32][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` is a variable of type [Structure][] | + +#### Result + +As no value is passed into the [Input Variable][] `($)NumberToSquare` for the [Flow][Flow Property] `square-number-flow` the default of `10` is used, which results in `100` being saved to the [Output Variable][] `($)SquaredNumber`. This results in the variable `($)Outputs` being updated to the following: + +```json +{ + "SquaredNumber": 100 +} +``` + +For more information see [Default Values][]. + +*** + +### Running a Flow that Throws an Exception + +This example will run the [Flow][Flow Property] `square-number-flow` saving the output variables to `($)Outputs`. + +The [Flow][Flow Property] `square-number-flow` takes an [Input Variable][] `($)NumberToSquare`, which is then multiplied by itself and saved to the [Output Variable][] `($)SquaredNumber`. If no value is given for `($)NumberToSquare` the default value `10` is used. The flow contains a block that checks that the [Input Variable][] `($)NumberToSquare` is larger than `0`, an exception is thrown by `square-number-flow` if `($)NumberToSquare` is not larger than `0`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Flow][Flow Property] | [Flow][Flow Property], with value `square-number-flow` | [Flow][Flow Property] is of type [FlowReference][] | +| [Inputs][Inputs Property] | | [Inputs][Inputs Property] is of type [InputVariables][] | +| > NumberToSquare | `($)NumberToSquare`, with value `-1` | `($)NumberToSquare` is of type [Int32][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` is a variable of type [Structure][] | + +#### Result + +The [Flow][Flow Property] `square-number-flow` contains a block that checks that the [Input Variable][] `($)NumberToSquare` is larger than `0`; if this is not the case an exception is thrown. + +In this example, as `-1` is passed into the [Input Variable][] `($)NumberToSquare` and is not greater than `0`, `($)Outputs` is not updated and an exception is thrown. For more information on how the exception is thrown and how to handle the exception see [Exceptions Thrown by a Child Flow][]. + +*** + +## Properties + +### Flow + +The [Flow][Flow Property] that will be run. + +The [Literal Editor][] is the only editor available for this property, and it provides the developer a list of all available flows to choose from. + +| | | +|--------------------|---------------------------| +| Data Type | [FlowReference][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][Literal Editor] | +| Default Value | No value (defaults to `null`) | + +### Inputs + +The [Input Variables][Input Variable] that are passed to the [Flow][Flow Property] that will be run. + +It is recommended to use the [Literal Editor][] for this property as it detects and warns of changes to the Flow Contract, allowing users to [Sync the Editor][Syncing the Inputs Property with the Flow Contract]. + +| | | +|--------------------|---------------------------| +| Data Type | [InputVariables][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][Literal Editor] | +| Default Value | No initial value (Will be [synced][Syncing the Inputs Property with the Flow Contract] when the [Flow][Flow Property] is first [selected][Selecting a Flow]) | + +### Outputs + +The [Output Variables][Output Variable] from the [Flow][Flow Property]. + +Each of the [Output Variables][Output Variable] will be saved to a [Structure][], where the key is the name of the variable and the item is the value of the variable. + +| | | +|--------------------|---------------------------| +| Data Type | [Structure][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][Variable Editor] | +| Default Value | `($)Outputs` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|------|-------------| +| [InvalidInputVariablesException][] | Thrown when [Inputs][Inputs Property] is missing any [Input Variables][Input Variable] from the chosen [Flow][Flow Property]. See [Missing Input Variables][]. | +| | Thrown when [Inputs][Inputs Property] has any extra [Input Variables][Input Variable] that are not in the chosen [Flow][Flow Property]. See [Extra Input Variables][]. | +| | Thrown when [Inputs][Inputs Property] has any [Input Variables][Input Variable] that are not a valid type for [Input Variable][]. See [Input Variables of an Invalid Type][]. | + +## Remarks + +### Selecting a Flow + +{{< figure src="/images/run-flow-selecting-a-flow.gif" >}} + +A flow can be selected using the [Literal Editor][] on the [Flow Property][], a list of all available flows will be presented to the developer and can be searched by the Name or Id of a flow. + +When a [Flow][Flow Property] is selected the [Inputs Property][] will be [Synced with the Flow Contract][Syncing the Inputs Property with the Flow Contract]. + +### Default Values + +If an [Input Variable][] has a default value, then this default value will be used when running the [Flow][Flow Property] if the corresponding value in the [Inputs Property][] is left empty. See [Running a Flow with Default Input Variables][] for an example. + +Also, if an [Input Variable][] has a default value, and the corresponding value in the [Inputs Property][] is not of the same type, a [Validation Error][] will be raised when the flow is validated. + +For more information see [Input Variables][Input Variable]. + +### Exceptions Thrown by a Child Flow + +If the [Flow][Flow Property] run by the Run Flow block throws an exception that is unhandled then it is rethrown by the Run Flow block. This can then be handled by any connected [Handle Block Exception blocks][]. See [Running a Flow that Throws an Exception][] for an example. + +If an exception thrown by a block is not handled by any connected [Handle Block Exception blocks][], it will be passed to the [Handle Workspace Exception][] block on the same workspace. + +This process repeats until: + +- The exception is handled, or +- The exception reaches the flow's top-level workspace, is not handled by any [Handle Block Exception blocks][] and the top-level workspace does not contain a [Handle Workspace Exception][] block. At this stage, the exception is handled by the flow's [Handle Flow Exception][] block. + +For more information see [Handling Exceptions][]. + +### Syncing the Inputs Property with the Flow Contract + +{{< figure src="/images/run-flow-contract-change.gif" >}} + +When a flow is first selected the [Inputs Property][] will be synced with the Flow Contract. + +When the contract of the flow changes (e.g. [Input Variables][Input Variable] of a called [Flow][Flow Property] are updated), a prompt will appear when the block is selected, allowing the user to sync the editor. + +This will cause: + +- Any missing [Input Variables][Input Variable] not present in the [Inputs Property][] to be added +- Any extra [Input Variables][Input Variable] present in the [Inputs Property][] to be removed +- Any [Input Variables][Input Variable] already present in the [Inputs Property][] to be retained + +[Undoing][] this action will cause the [Inputs Property][] to return to its previous state, from before it was synced, allowing any data to be retrieved from any extra [Input Variables][Input Variable]. + +### Known Limitations + +#### The Flow Property can only use the Literal Editor + +The Literal Editor is the only editor available for the [Flow Property][] + +In future this limitation may be removed. + +#### Syncing the Inputs Property with the Flow Contract is not available when using editors other than the Literal Editor + +[Syncing the Inputs Property with the Flow Contract][] is only available when the [Inputs Property][] uses the [Literal Editor][]. If any other editor is used, the prompt to sync will not be displayed and any changes will need to be resolved manually. + +[Flow Property]: {{< ref "#flow" >}} +[Inputs Property]: {{< ref "#inputs" >}} +[Outputs Property]: {{< ref "#outputs" >}} +[Syncing the Inputs Property with the Flow Contract]: {{< ref "#syncing-the-inputs-property-with-the-flow-contract" >}} +[Selecting a Flow]: {{< ref "#selecting-a-flow" >}} +[Running a Flow that Throws an Exception]: {{< ref "#running-a-flow-that-throws-an-exception" >}} +[Running a Flow with Default Input Variables]: {{< ref "#running-a-flow-with-default-input-variables" >}} +[Default Values]: {{< ref "#default-values" >}} +[Exceptions Thrown by a Child Flow]: {{< ref "#exceptions-thrown-by-a-child-flow" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Literal Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Input Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} +[Output Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Validation Error]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.MainDoc" >}} + +[Undoing]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.Undo" >}} + +[FlowReference]: {{< url path="Cortex.Reference.DataTypes.Flows.FlowReference.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[InputVariables]: {{< url path="Cortex.Reference.DataTypes.Flows.InputVariables.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} + +[InvalidInputVariablesException]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.MainDoc" >}} +[Missing Input Variables]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.MissingInputVariables" >}} +[Extra Input Variables]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.ExtraInputVariables" >}} +[Input Variables of an Invalid Type]: {{< url path="Cortex.Reference.Exceptions.Flows.Execution.InvalidInputVariablesException.InputVariablesOfAnInvalidType" >}} + +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/_index.md b/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/_index.md new file mode 100644 index 000000000..80df19ef8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/_index.md @@ -0,0 +1,5 @@ +--- +title: "Start Flow" +linkTitle: "Start Flow" +description: "Blocks that indicate the start of a flow." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/start-flow-block.md b/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/start-flow-block.md new file mode 100644 index 000000000..e76575d33 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/flows/start-flow/start-flow-block.md @@ -0,0 +1,37 @@ +--- +title: "Start Flow" +linkTitle: "Start Flow" +description: "Indicates the start of a flow." +--- + +{{< figure src="/blocks/flows-start-flow-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Flows.StartFlow.StartFlowBlock)
+ +## Description + +Indicates the start of a flow. + +This is always the first block in a flow. It cannot be deleted, and a flow can only contain one of these blocks. + +The block has no block specific properties, but it does have the `Description` property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. + +A breakpoint can be added to this block when debugging. + +## Examples + +No examples for the block. + +## Properties + +No properties for the block, other than the `Description` property that is common to all blocks. + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +None diff --git a/content/en/docs/2023.9/Reference/Blocks/google-workspace/_index.md b/content/en/docs/2023.9/Reference/Blocks/google-workspace/_index.md new file mode 100644 index 000000000..8d6e24e3f --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/google-workspace/_index.md @@ -0,0 +1,5 @@ +--- +title: "Google Workspace" +linkTitle: "Google Workspace" +description: "Blocks related to working with Google Workspace." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/_index.md b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/_index.md new file mode 100644 index 000000000..f53ba8b4b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/_index.md @@ -0,0 +1,5 @@ +--- +title: "Gmail" +linkTitle: "Gmail" +description: "Blocks related to working with Gmail." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/_index.md b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Send Email" +linkTitle: "Send Email" +description: "Blocks related to sending Emails." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/send-email-using-gmail-block.md b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/send-email-using-gmail-block.md new file mode 100644 index 000000000..4d0c530e2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/google-workspace/gmail/send-email/send-email-using-gmail-block.md @@ -0,0 +1,741 @@ +--- +title: "Send Email Using Gmail" +linkTitle: "Send Email Using Gmail" +description: "Sends an email using the SMTP server hosted by Gmail." +--- + +{{< figure src="/blocks/google-workspace-send-email-using-gmail-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmailBlock)
+ +## Description + +Connects to the [SMTP][] server hosted by [Gmail][] using the specified [Gmail Session Details][Gmail Session Details Property], and sends an [Email Message][Email Message Property]. + +[Close Session][Close Session Property] can be specified to choose whether the connection to the [SMTP][] server hosted by [Gmail][] is closed or is kept open for use on subsequent Send Email Using Gmail blocks. + +## Examples + +Sending emails using a username and password is not recommended and is being phased out by [Gmail][]. Using a username and password will currently only work for [Gmail][] accounts associated with a Google Workspace that has access enabled for less secure apps. Instead, it is recommended to use an app password or OAuth, for more information, see [Less Secure Apps][]. + +In the following examples, where a [UserCredentials][] is used in the [Gmail Session Details][Gmail Session Details Property], the [Password][] property can be either the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password. + +For more information, see [Setting Credentials][]. + +### Sending an email to a single recipient + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com`. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be to set to `true` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information about when [UseSsl][] should be set to `true` or `false`, see [Setting UseSsl][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Email Message][Email Message Property] | `($)EmailMessage` with value `{"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`Example paragraph text
" +``` + +[Outlook][] will display the email body as follows: + +{{< figure src="/images/send-email-using-smtp-server-html-email.png" >}} + +For more information on how the body of an email will be displayed, see the help provided by the respective email client. + +### Attachments + +Attachments can be sent in an email by providing a list of file paths in the [Attachments][] property of the [Email Message][Email Message Property]. For more information concerning attaching files to an email, see the sections below. + +#### Supported file path formats + +Each file path in the [Attachments][] within the [Email Message][Email Message Property] can be an: + +- Absolute file path +- Relative file path +- UNC file path + +where each file path must be accessible from the server executing the flow. + +For more information about each of these supported file path formats, please see [File & Folder Paths][]. + +#### File paths need escaping + +Each file path in the [Attachments][] within the [Email Message][Email Message Property] requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow. + +Escaping can be done in two ways: + +- Escaping the `\` character with another `\` character (e.g. `"C:\\Attachments\\attachment.txt"`), or +- Prepending an `@` character before the start of the File Path (e.g. `@"C:\Attachments\attachment.txt"`) + +#### Null file path + +If `null` is provided as a file path in the [Attachments][] within the [Email Message][Email Message Property], an [ArgumentNullException][] is thrown. + +#### Empty file path + +If an empty string is provided as a file path in the the [Attachments][] within the [Email Message][Email Message Property], an [ArgumentException][] is thrown. + +#### File path does not exist + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] does not exist, a [FileNotFoundException][] is thrown. + +#### Invalid file path + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] is invalid (i.e. contains any of the following characters: ", *, ?, |, <, >, :, \, /), an [IOException][] will be thrown. + +#### File path points to a folder + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] points to a folder, an [UnauthorizedAccessException][] will be thrown. + +#### File path contains leading spaces + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] contains leading spaces they are not removed and an [IOException][] will be thrown; however, trailing spaces are removed. + +#### File path contains only whitespace or the NUL character + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] contains only whitespace (i.e. `" "`) or the NUL character (i.e. `\0`), an [ArgumentException][] will be thrown. + +#### File path exceeds the system-defined maximum length + +If a file path in the [Attachments][] within the [Email Message][Email Message Property] exceeds the system-defined maximum length (typically 32,767), a [PathTooLongException][] will be thrown. + +#### User does not have necessary permissions to attach the file + +If the user the flow is executing as does not have permissions to access the file at the provided file path in the [Attachments][] within the [Email Message][Email Message Property], an [UnauthorizedAccessException][] will be thrown. + +#### Attachment size limit + +The combined size of all the [Attachments][] within the [Email Message][Email Message Property] must be less than the limit specified by the email service provider. If the combined size of all of the attachments is greater than the limit, an [SmtpCommandException][] will be thrown. + +For [Outlook][] this is `20 MB` and for [Gmail][] this is `25 MB`, for more information on the size limits for other email service providers, see the help provided by the respective email service provider. + +### Supported formats for ServerDetails.Host + +The following formats are supported for [Host][] in [ServerDetails][]: + +- Fully Qualified Domain Name (e.g. `"smtp.gmail.com"`) + +### Setting UseSsl + +The [ServerDetails][] within the [Gmail Session Details][Gmail Session Details Property] specifies which [SMTP][] server to connect to. The value of the [UseSsl][] property inside this object depends on the [Host][] and [Port][] being connected to. There are two types of [SSL][]/[TLS][] connections that can occur: + +- [SSL][]/[TLS][] is used as soon as a connection is established +- [SSL][]/[TLS][] is used via the STARTTLS command if it is available + +The above two points correspond to the [UseSsl][] property being set to `true` and `false` respectively. As such, generally the following rules can be followed to determine whether [UseSsl][] should be set to `true` or `false`: + +- If the [Port][] being connected to is `465` then [UseSsl][] should be set to `true` +- If the [Port][] being connected to is `25` or `587` then [UseSsl][] should be set to `false` + +### Setting Credentials + +The [Credentials][Credentials Property] within the [Gmail Session Details][Gmail Session Details Property] specifies what user to connect as on the [SMTP][] server hosted by [Gmail][]. Two types of authentication are supported: + +- Basic +- OAuth (Two-Legged OAuth) + +The above two authentication mechanisms correspond to the [Credentials][Credentials Property] within the [Gmail Session Details][Gmail Session Details Property] being a [UserCredentials][] and a [GmailOAuthCertificateCredentials][] respectively. + +#### Setting Credentials to UserCredentials + +Currently, [Gmail][] will not allow emails to be sent using the username and password of an account unless the account is associated with a Google Workspace account. + +As such, the recommended approach for using a [UserCredentials][] as the [Credentials][Credentials Property] within the [Gmail Session Details][Gmail Session Details Property] is to set up an app password and use that in place of the actual password associated with the account, see [Setting up an app password for a Gmail account][] for more information. + +Note the following: + +- The value of the [Username][] property may optionally be encrypted, however the [Password][] should be encrypted. +- Note that the [UserCredentials][] also contains a [Domain][] property which is ignored by this block. + +#### Setting Credentials to GmailOAuthCertificateCredentials + +In order to use OAuth as the authentication mechanism: + +- A client application must be set up on the Google Workspace +- A service account must be set up for the client application +- A private key (.p12 file) must be generated for the service account +- An administrator of the Google Workspace must grant the client application domain-wide delegation for the scope `https://mail.google.com/` + +For more information on how to configure a [Gmail][] account to work with OAuth, see [Setting up a Gmail account for OAuth authentication][]. + +Once the account has been set up to work with OAuth, a [GmailOAuthCertificateCredentials][] can be used as the [Credentials][Credentials Property] within the [Gmail Session Details][Gmail Session Details Property]. The properties in the [GmailOAuthCertificateCredentials][] correspond with the client application data as follows: + +- [CertificatePath][] - The path pointing to the certificate (.p12) file generated when setting up the client application; the certificate must be accessible from the server executing the flow, for more information on using a certificate file, see [Certificate Files][]. +- [CertificatePassword][] - The password associated with the certificate (.p12) +- [FromAddress][] - The address of the account used to set up the client application +- [ClientId][] - The Client ID of the client application + +Note that the values of the [CertificatePath][] and [ClientId][] properties may optionally be encrypted, however the [CertificatePassword][] should be encrypted. + +For more detailed information on each of these properties, see [GmailOAuthCertificateCredentials][]. + +### Certificate Files + +OAuth can be used as the authentication mechanism when sending an email using this block by providing a [GmailOAuthCertificateCredentials][] as the [Credentials][Credentials Property] in the [Gmail Session Details][Gmail Session Details Property]. [GmailOAuthCertificateCredentials][] requires a [CertificatePath][] to be provided, which is a path pointing to a certificate file accessible from the server executing the flow. For more information concerning using a certificate, see the sections below. + +#### Supported CertificatePath formats + +The [CertificatePath][] within the [GmailOAuthCertificateCredentials][] can be an: + +- Absolute file path +- Relative file path +- UNC file path + +where each file path must be accessible from the server executing the flow. + +For more information about each of these supported file path formats, please see [File & Folder Paths][]. + +#### CertificatePath needs escaping + +The [CertificatePath][] within the [GmailOAuthCertificateCredentials][] requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow. + +Escaping can be done in two ways: + +- Escaping the `\` character with another `\` character (e.g. `"C:\\Certificates\\certificate.p12"`), or +- Prepending an `@` character before the start of the File Path (e.g. `@"C:\Certificates\certificate.p12"`) + +#### Null CertificatePath + +If `null` is provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][], a [PropertyNullException][] is thrown. + +#### Empty CertificatePath + +If an empty string is provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][], a [PropertyEmptyException][] is thrown. + +#### CertificatePath does not exist + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] does not exist, an [EmailSessionException][] is thrown. For more information, see [Invalid SSL Certificate][]. + +#### Invalid CertificatePath + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] is invalid (i.e. contains any of the following characters: ", *, ?, |, <, >, :, \, /), an [EmailSessionException][] will be thrown. For more information, see [Invalid SSL Certificate][]. + +#### CertificatePath points to a folder + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] points to a folder, an [EmailSessionException][] will be thrown. For more information, see [Invalid SSL Certificate][]. + +#### CertificatePath contains leading spaces + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] contains leading spaces they are not removed and an [EmailSessionException][] will be thrown; however, trailing spaces are removed. For more information, see [Invalid SSL Certificate][]. + +#### CertificatePath contains only whitespace or the NUL character + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] contains only whitespace (i.e. `" "`) or the NUL character (i.e. `\0`), an [EmailSessionException][] will be thrown. For more information, see [Invalid SSL Certificate][]. + +#### CertificatePath exceeds the system-defined maximum length + +If the path provided as the [CertificatePath][] within the [GmailOAuthCertificateCredentials][] exceeds the system-defined maximum length (typically 32,767), an [EmailSessionException][] will be thrown. For more information, see [Invalid SSL Certificate][]. + +#### User does not have necessary permissions to use the certificate file + +If the user the flow is executing as does not have permissions to access the file at the [CertificatePath][] within the [GmailOAuthCertificateCredentials][], an [EmailSessionException][] will be thrown. For more information, see [Invalid SSL Certificate][]. + +### Opening Sessions + +The Send Email Using Gmail block automatically handles creating and opening sessions for the specified [Gmail Session Details][Gmail Session Details Property] using the following rules: + +- If a session does not exist, a new session will be created, opened and used when the block runs. +- If a session already exists but is closed, the session will be opened and used when the block runs. +- If a session already exists and is open, the session will be used when the block runs. + +[Gmail Session Details][Gmail Session Details Property] will keep the session open across multiple Send Email Using Gmail blocks as long as [Close Session][Close Session Property] is set to `false`. Keeping the session open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening sessions for each execution. + +Note that for all [SSL][] connections, the protocol to be used will be negotiated with the server depending on which protocols are available. Similarly, the [SASL][] mechanism to be used will be negotiated with the mail server based on the available mechanisms. + +For information on how to explicitly close a session, please see [Closing Sessions][]. + +### Closing Sessions + +Sessions can be explicitly closed by setting [Close Session][Close Session Property] to `true`. This causes the session to be closed after the [Email Message][Email Message Property] has been sent. + +If [Close Session][Close Session Property] is set to `false` the session will be closed when the [Variable][] that [Gmail Session Details][Gmail Session Details Property] is set to goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see [Variables][]. + +For information on how to open a session, please see [Opening Sessions][]. + +### Known Limitations + +None + +[Email Message Property]: {{< ref "#email-message" >}} +[Gmail Session Details Property]: {{< ref "#gmail-session-details" >}} +[Close Session Property]: {{< ref "#close-session" >}} +[How does Priority affect sending an email?]: {{< ref "#how-does-priority-affect-sending-an-email" >}} +[How does BodyFormat affect sending an email?]: {{< ref "#how-does-bodyformat-affect-sending-an-email" >}} +[Attachments Remarks]: {{< ref "#attachments" >}} +[Supported formats for ServerDetails.Host]: {{< ref "#supported-formats-for-serverdetailshost" >}} +[Setting Credentials]: {{< ref "#setting-credentials" >}} +[Setting UseSsl]: {{< ref "#setting-usessl" >}} +[Certificate Files]: {{< ref "#certificate-files" >}} +[Opening Sessions]: {{< ref "#opening-sessions" >}} +[Closing Sessions]: {{< ref "#closing-sessions" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[EmailMessage]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.MainDoc" >}} +[To]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.To" >}} +[From]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.From" >}} +[Cc]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Cc" >}} +[Bcc]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Bcc" >}} +[Priority]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Priority" >}} +[Subject]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Subject" >}} +[BodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.BodyFormat" >}} +[Body]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Body" >}} +[Attachments]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.Attachments" >}} +[creating an EmailMessage using a constructor]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.CreateAnEmailMessage" >}} + +[GmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails.MainDoc" >}} +[ServerDetails Property]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails.ServerDetails" >}} +[Credentials Property]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails.Credentials" >}} + +[ServerDetails]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.MainDoc" >}} +[Host]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Host" >}} +[Port]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Port" >}} +[UseSsl]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.UseSsl" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[Domain]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Domain" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[GmailOAuthCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials.MainDoc" >}} +[CertificatePath]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials.CertificatePath" >}} +[CertificatePassword]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials.CertificatePassword" >}} +[FromAddress]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials.FromAddress" >}} +[ClientId]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials.ClientId" >}} + +[EmailAddress]: {{< url path="Cortex.Reference.DataTypes.Email.EmailAddress.MainDoc" >}} +[Address]: {{< url path="Cortex.Reference.DataTypes.Email.EmailAddress.Address" >}} + +[EmailMessagePriority]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.MainDoc" >}} +[Normal]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.Normal" >}} +[Urgent]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.Urgent" >}} +[NonUrgent]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.NonUrgent" >}} + +[EmailMessageBodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.MainDoc" >}} +[HTML]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.HTML" >}} +[Text]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.Text" >}} + +[Setting up an app password for a Gmail account]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.Authentication.SettingUpAppPassword" >}} +[Setting up a Gmail account for OAuth authentication]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.Authentication.SettingUpOAuthGmail" >}} + +[EmailSessionException]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.MainDoc" >}} +[Invalid Port]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidPort" >}} +[Invalid Host]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidHost" >}} +[SSL Required]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslRequired" >}} +[SSL Unsupported]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslUnsupported" >}} +[Invalid User Credentials]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidUserCredentials" >}} +[Invalid SSL Certificate]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidSslCertificate" >}} +[Invalid Gmail Client Credentials]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidClientCredentials" >}} +[EmailSessionErrorCode Limitations]: {{< url path="Cortex.Reference.DataTypes.Email.EmailSessionErrorCode.Limitations" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} +[FileNotFoundException]: {{< url path="MSDocs.DotNet.Api.System.IO.FileNotFoundException" >}} +[IOException]: {{< url path="MSDocs.DotNet.Api.System.IO.IOException" >}} +[PathTooLongException]: {{< url path="MSDocs.DotNet.Api.System.IO.PathTooLongException" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} +[Property Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyIsInvalid">}} +[SmtpCommandException]: {{< url path="MimeKit.Docs.SmtpCommandException" >}} +[UnauthorizedAccessException]: {{< url path="MSDocs.DotNet.Api.System.UnauthorizedAccessException" >}} + +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[File & Folder Paths]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.Paths.MainDoc" >}} + +[SASL]: {{< url path="Cortex.Reference.Glossary.P-T.SASL" >}} +[SMTP]: {{< url path="Cortex.Reference.Glossary.P-T.SMTP" >}} +[SSL]: {{< url path="Cortex.Reference.Glossary.P-T.SSL" >}} +[TLS]: {{< url path="Cortex.Reference.Glossary.P-T.TLS" >}} +[BCC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.BCC" >}} +[CC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.CC" >}} +[CRL]: {{< url path="Cortex.Reference.Glossary.A-E.CRL" >}} +[Gmail]: {{< url path="Cortex.Reference.Glossary.F-J.Gmail" >}} +[Outlook]: {{< url path="Cortex.Reference.Glossary.K-O.Outlook" >}} + +[Less Secure Apps]: {{< url path="Google.Authentication.LessSecureApps.MainDoc" >}} +[RFC 5321]: {{< url path="IETF.Email.RFC5321" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/http/_index.md b/content/en/docs/2023.9/Reference/Blocks/http/_index.md new file mode 100644 index 000000000..473bf9830 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/http/_index.md @@ -0,0 +1,5 @@ +--- +title: "Http" +linkTitle: "Http" +description: "Blocks related to working with HTTP." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/_index.md b/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/_index.md new file mode 100644 index 000000000..2afeb1c3a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute Http Request" +linkTitle: "Execute Http Request" +description: "Blocks related to executing HTTP requests." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/execute-http-request-block-1.md b/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/execute-http-request-block-1.md new file mode 100644 index 000000000..2e0eec183 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/http/execute-http-request/execute-http-request-block-1.md @@ -0,0 +1,518 @@ +--- +title: "Execute Http Request" +linkTitle: "Execute Http Request" +description: "Executes an HTTP request and returns a response." +--- + +{{< figure src="/blocks/http-execute-http-request-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequestBlock`1)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Executes an [Http Request][Http Request Property] using the specified [Http Credentials][Http Credentials Property] and returns the [Http Response][Http Response Property]. + +## Examples + +The following examples will use an example [API][] with a base [Uri][] of `https://test-shop.com/api` and resource called `items` at `https://test-shop.com/api/items`. Each example assumes that the resource `items` contains the following data before the example is executed: + +```json +[ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + } +] +``` + +The example [API][] supports: + +- Retrieval of every item in the `items` resource via a [GET][] request which returns the `items` resource as the [ResponseBody][] of the [Http Response][Http Response Property] +- Creation of a new item in the `items` resource via a [POST][] request which returns the updated `items` resource as the [ResponseBody][] of the [Http Response][Http Response Property] +- Unauthenticated requests +- Basic authentication +- Retrieval of access tokens from `https://test-shop.com/api/oauth2/token` +- OAuth authentication using password credentials +- OAuth authentication using client credentials + +### Executing a GET request + +This example will send a [GET][] request to `https://test-shop.com/api/items` using [HTTP 1.1][HTTP11] with no authentication which requires [Http Credentials][Http Credentials Property] to be `null`. + +Note that the result of executing an [Http Request][Http Request Property] is dependent on the [API][] that the request is being made to. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Http Request][Http Request Property] | `($)HttpRequest`, with value `{"QueryStringParameters": null, "Verb": "RequestVerb.GET", "ContentType": null, "Body": null, "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`(Cortex.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequestBlock`1)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Executes a [Soap Request][Soap Request Property] using the specified [Http Credentials][Http Credentials Property] and returns the [Soap Response][Soap Response Property]. + +## Examples + +The following examples will use an example SOAP service with a base [Uri][] of `https://test-converter.com/xml`. + +The example SOAP service supports the following: + +- Conversion of a temperature in Degrees Celcius to Kelvin using an [Action][] of `https://test-converter.com/DegreesToKelvin` +- Unauthenticated requests +- Basic authentication +- Retrieval of access tokens from `https://test-converter.com/oauth2/token` +- OAuth authentication using password credentials +- OAuth authentication using client credentials + +### Executing a request using SOAP 1.1 + +This example will send a [Soap Request][Soap Request Property] to `https://test-converter.com/xml` using SOAP 1.1 with no authentication which requires: + +- [SoapMessage][SoapMessage Property] to be a [Soap11Message][] +- [Http Credentials][Http Credentials Property] to be `null` + +Note that the result of executing a [Soap Request][Soap Request Property] is dependent on the SOAP service that the request is being made to. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Soap Request][Soap Request Property] | `($)SoapRequest`, with value `{"SoapMessage": {"Action": "https://test-converter.com/DegreesToKelvin", "Envelope": "(Cortex.Blocks.Json.ConvertJson.ConvertJsonToObjectBlock)
+ +## Description + +Converts [Json][Json Property] to an [Object][Object Property]. + +An additional [Settings][Settings Property] option can be specified to control how the conversion should deal with things such as: + +* `null` objects +* Date Time formats and offsets +* Number formats +* Text escaping +* Type information + +For information about the default [Settings][Settings Property] used if none are specified, as well as all other options that can be configured, please see [JsonSerializerSettings][]. + +## Examples + +### Convert Json to a List (without Type information) + +This example will convert `"[[1, 2, 3], [4, 5, 6]]"` into a [List][]<[Object][]>. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Json][Json Property] | `($)Json`, with value `"[[1, 2, 3], [4, 5, 6]]"` | `($)Json` is a variable of type [String][] | +| [Settings][Settings Property] | `($)Settings`, with value `null` | `($)Settings` is a variable of type [JsonSerializerSettings][] | +| [Object][Object Property] | `($)Object`, with no value | `($)Object` is a variable that will be set to a [dynamic][] value (i.e. in this example to a [List][]<[Object][]>). | + +#### Result + +Converting `"[[1, 2, 3], [4, 5, 6]]"` to an object results in the variable `($)Object` being updated to the following: + +```json +[ + [ + 1, + 2, + 3 + ], + [ + 4, + 5, + 6 + ] +] +``` + +As the Json does not include any type information, `($)Object` will be a [List][]<[Object][]>, rather than a [List][]<[List][]<[Int32][]>>. This is because when performing the conversion there is no type information to tell the converter that the items in the list are [List][]<[Int32][]> data types. + +See [Convert Json to a List (with Type information)][] for an example on how to include type information in the Json. + +*** + +### Convert Json to a List (with Type information) + +This example will convert `"[[1, 2, 3], [4, 5, 6]]"` into a [List][]<[List][]<[Int32][]>>, rather than a [List][]<[Object][]> as above. + +For this to work, type information needs to be included in the Json representation. This can be seen below: + +```json +{ + "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib", + "$values": [ + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [1,2,3] + }, + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [4,5,6] + } + ] +} +``` + +Realistically, this example is only useful if you have already produced Json including type information by using the [Convert Object To Json][] block. If this is the case, you can then convert it back with the correct data types. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Json][Json Property] | `($)Json`, with complex value as shown above | `($)Json` is a variable of type [String][] | +| [Settings][Settings Property] | `($)Settings`, with value `new JsonSerializerSettings{TypeNameHandling = TypeNameHandling.All}` | `($)Settings` is a variable of type [JsonSerializerSettings][] | +| [Object][Object Property] | `($)Object`, with no value | `($)Object` is a variable that will be set to a [dynamic][] value (i.e. in this example to a [List][]<[List][]<[Int32][]>>). | + +#### Result + +Converting: + +```json +{ + "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib", + "$values": [ + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [1,2,3] + }, + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [4,5,6] + } + ] +} +``` + +to an object results in the variable `($)Object` being updated to the following: + +```json +[ + [ + 1, + 2, + 3 + ], + [ + 4, + 5, + 6 + ] +] +``` + +As the Json does include type information, `($)Object` will be a [List][]<[List][]<[Int32][]>>, rather than a [List][]<[Object][]>. + +*** + +## Properties + +### Json + +The [Json][Json Property] to convert into an [Object][Object Property]. + +During the conversion it will be attempted to convert the [Json][Json Property] to the correct data type where possible. If the correct data type cannot be determined, then collection data types will be converted to a [List][]<[dynamic][]>, and other objects will be converted to a [Structure][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Json` with no value | + +### Settings + +Optional [Settings][Settings Property] that can be specified to control how the conversion should deal with things such as: + +* `null` objects +* Date Time formats and offsets +* Number formats +* Text escaping + +For information about the default [Settings][Settings Property] used if none are specified, as well as all other options that can be configured, please see [JsonSerializerSettings][]. + +| | | +|--------------------|---------------------------| +| Data Type | [JsonSerializerSettings][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `new JsonSerializerSettings {}` | + +### Object + +The [Object][Object Property] that has been converted from [Json][Json Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Object` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [JsonReaderException][] | Thrown when an error occurs reading the [Json][Json Property]. | +| [JsonSerializationException][] | Thrown when an error occurs converting the [Json][Json Property] to an [Object][Object Property]. | +| [PropertyEmptyException][] | Thrown when [Json][Json Property] is empty (i.e. `""`). | +| [PropertyNullException][] | Thrown when [Json][Json Property] is `null`. | + +## Remarks + +### "{}" Json + +If [Json][Json Property] is set to the text `"{}"`, [Object][Object Property] will be set to an empty [Structure][]. + +### "[]" Json + +If [Json][Json Property] is set to the text `"[]"`, [Object][Object Property] will be set to an empty [List][]<[dynamic][]>. + +### "null" Json + +If [Json][Json Property] is set to the text `"null"`, [Object][Object Property] will be set to `null`. + +### Round-tripping + +For most data types it should be possible to pass the Json created by a [Convert Object To Json][] block to this block, and then pass the [Object][Object Property] created by this block back to a [Convert Object To Json][] block; this is called round-tripping. + +It should be noted however, that not all data types will be able to be round-tripped. + +An example of a data type that is not able to be round-tripped is [HttpRequestHeaders][]. As it does not contain a public constructor it will not be able to be converted from its Json representation back into an [HttpRequestHeaders][]; instead a [JsonSerializationException][] will be thrown with a message like: `"Cannot create and populate list type System.Net.Http.Headers.HttpRequestHeaders"`. + +[Json Property]: {{< ref "#json" >}} +[Settings Property]: {{< ref "#settings" >}} +[Object Property]: {{< ref "#object" >}} + +[Convert Json to a List (with Type information)]: {{< ref "#convert-json-to-a-list-with-type-information" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[JsonReaderException]: {{< url path="JsonDotNet.JsonReaderException" >}} +[JsonSerializationException]: {{< url path="JsonDotNet.JsonSerializationException" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[HttpRequestHeaders]: {{< url path="Cortex.Reference.DataTypes.MostCommon.HttpRequestHeaders" >}} +[JsonSerializerSettings]: {{< url path="Cortex.Reference.DataTypes.Json.JsonSerializerSettings.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/json/convert-json/convert-object-to-json-block.md b/content/en/docs/2023.9/Reference/Blocks/json/convert-json/convert-object-to-json-block.md new file mode 100644 index 000000000..e12b09183 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/json/convert-json/convert-object-to-json-block.md @@ -0,0 +1,191 @@ +--- +title: "Convert Object To Json" +linkTitle: "Convert Object To Json" +description: "Converts an Object To Json." +--- + +{{< figure src="/blocks/json-convert-to-json-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Json.ConvertJson.ConvertObjectToJsonBlock)
+ +## Description + +Converts an [Object][Object Property] to [Json][Json Property]. + +An additional [Settings][Settings Property] option can be specified to control how the conversion should deal with things such as: + +* `null` objects +* Date Time formats and offsets +* Number formats +* Text escaping +* Type information + +For information about the default [Settings][Settings Property] used if none are specified, as well as all other options that can be configured, please see [JsonSerializerSettings][]. + +## Examples + +### Convert a List to Json (without Type information) + +This example will convert `[[1, 2, 3], [4, 5, 6]]` to its Json representation, without including type information. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Object][Object Property] | `($)Object`, with value `[[1, 2, 3], [4, 5, 6]]` | `($)Object` is a variable of type [List][]<[List][]<[Int32][]>> | +| [Settings][Settings Property] | `($)Settings`, with value `null` | `($)Settings` is a variable of type [JsonSerializerSettings][] | +| [Json][Json Property] | `($)Json`, with no value | `($)Json` is a variable that will be set to a [String][] value. | + +#### Result + +Converting `[[1, 2, 3], [4, 5, 6]]` to Json results in the variable `($)Json` being updated to the following: + +```json +"[[1, 2, 3],[4, 5, 6]]" +``` + +As the resultant Json does not include any type information, if this Json was then used as input to the [Convert Json To Object][] block, the resultant object would be a [List][]<[Object][]>, rather than a [List][]<[List][]<[Int32][]>>. + +See [Convert a List To Json (with Type information)][] for an example on how to include type information in the Json. + +*** + +### Convert a List to Json (with Type information) + +This example will convert `[[1, 2, 3], [4, 5, 6]]` to its Json representation, including type information. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Object][Object Property] | `($)Object`, with value `[[1, 2, 3], [4, 5, 6]]` | `($)Object` is a variable of type [List][]<[List][]<[Int32][]>> | +| [Settings][Settings Property] | `($)Settings`, with value `new JsonSerializerSettings{TypeNameHandling = TypeNameHandling.All}` | `($)Settings` is a variable of type [JsonSerializerSettings][] | +| [Json][Json Property] | `($)Json`, with no value | `($)Json` is a variable that will be set to a [String][] value. | + +#### Result + +Converting `[[1, 2, 3], [4, 5, 6]]` to its Json representation (including type information) results in the variable `($)Json` being updated to the following: + +```json +{ + "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib", + "$values": [ + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [1,2,3] + }, + { + "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib", + "$values": [4,5,6] + } + ] +} +``` + +*** + +## Properties + +### Object + +The [Object][Object Property] to convert to [Json][Json Property]. + +[Object][Object Property] can be any data type. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Object` with no value | +### Settings + +Optional [Settings][Settings Property] that can be specified to control how the conversion should deal with things such as: + +* `null` objects +* Date Time formats and offsets +* Number formats +* Text escaping + +For information about the default [Settings][Settings Property] used if none are specified, as well as all other options that can be configured, please see [JsonSerializerSettings][]. + +| | | +|--------------------|---------------------------| +| Data Type | [JsonSerializerSettings][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `new JsonSerializerSettings {Formatting = Formatting.Indented}` | + +### Json + +The [Json][Json Property] that has been converted from [Object][Object Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Json` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [JsonSerializationException][] | Thrown when an error occurs converting the [Object][Object Property] to [Json][Json Property]. | + +## Remarks + +### Object is empty Structure or Object + +If [Object][Object Property] is set to an empty [Structure][] or [Object][], [Json][Json Property] is set to the text `"{}"`. + +### Object is empty List + +If [Object][Object Property] is set to an empty [List][], [Json][Json Property] is set to the text `"[]"`. + +### Null Object + +If [Object][Object Property] is set to `null`, [Json][Json Property] will be set to the text `"null"`. + +### Round-tripping + +For most data types it should be possible to pass the Json created by this block to the [Convert Json To Object][] block, and then pass the [Object][Object Property] created by the [Convert Json To Object][] block back to this block; this is called round-tripping. + +It should be noted however, that not all data types will be able to be round-tripped. + +An example of a data type that is not able to be round-tripped is [HttpRequestHeaders][]. As it does not contain a public constructor it will not be able to be converted from its Json representation back into an [HttpRequestHeaders][]; instead a [JsonSerializationException][] will be thrown with a message like: `"Cannot create and populate list type System.Net.Http.Headers.HttpRequestHeaders"`. + +[Object Property]: {{< ref "#object" >}} +[Json Property]: {{< ref "#json" >}} +[Settings Property]: {{< ref "#settings" >}} + +[Convert a List to Json (with Type information)]: {{< ref "#convert-a-list-to-json-with-type-information" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[JsonSerializationException]: {{< url path="JsonDotNet.JsonSerializationException" >}} + +[Convert Json To Object]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertJsonToObject.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[HttpRequestHeaders]: {{< url path="Cortex.Reference.DataTypes.MostCommon.HttpRequestHeaders" >}} +[JsonSerializerSettings]: {{< url path="Cortex.Reference.DataTypes.Json.JsonSerializerSettings.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/logs/_index.md b/content/en/docs/2023.9/Reference/Blocks/logs/_index.md new file mode 100644 index 000000000..e051eb041 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/logs/_index.md @@ -0,0 +1,5 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: "Blocks related to creating Logs." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/logs/log-event/_index.md b/content/en/docs/2023.9/Reference/Blocks/logs/log-event/_index.md new file mode 100644 index 000000000..1880a3453 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/logs/log-event/_index.md @@ -0,0 +1,5 @@ +--- +title: "Log Event" +linkTitle: "Log Event" +description: "Log events to the filesystem." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/logs/log-event/log-event-block.md b/content/en/docs/2023.9/Reference/Blocks/logs/log-event/log-event-block.md new file mode 100644 index 000000000..2112da8d2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/logs/log-event/log-event-block.md @@ -0,0 +1,392 @@ +--- +title: "Log Event" +linkTitle: "Log Event" +description: "Logs an event to the filesystem." +--- + +{{< figure src="/blocks/logs-log-event-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Logs.LogEvent.LogEventBlock)
+ +## Description + +Logs an [event][EventDetails Property] to the filesystem. + +Additional options can be specified: + +* [Event Type][EventType Property] can be specified to define the type of event being logged. +* [Event Severity][EventSeverity Property] can be specified to define the severity of the event being logged. +* [Started At][StartedAt Property] can be specified to define the Date and Time the event being logged started. +* [Ended At][EndedAt Property] can be specified to define the Date and Time the event being logged ended. + +## Examples + +### Log an event + +This example will log details about all tasks of a multi-stage process that provisions a new user at a company. + +* Process: `"Provision New User"` + * Stage: `"Configure Active Directory"` + * Task: `"Add User to Azure Active Directory"` + * Task: `"Add User to On-Premise Active Directory"` + * Stage: `"Configure Email"` + * Task: `"Create Outlook Account"` + * Task: `"Create Default Signature"` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Event Details][EventDetails Property] | `($)EventDetails`, with value `{"Process":{"Provision New User":{"Stages":[{"Configure Active Directory":{"Tasks":["Add User to Azure Active Directory","Add User to On-Premise Active Directory"]}},{"Configure Email":{"Tasks":["Create Outlook Account","Create Default Signature"]}}]}}}` | `($)EventDetails` is a variable of type [Structure][]. | +| [Event Type][EventType Property] | `($)EventType`, with value `"User Provisioning"` | `($)EventType` is a variable of type [String][]. | +| [Event Severity][EventSeverity Property] | `($)EventSeverity`, with value `EventSeverity.Information` | `($)EventSeverity` is a variable of type [Nullable][]<[EventSeverity][]>. | +| [Started At][StartedAt Property] | `($)StartedAt`, with value of [DateTimeOffset][] that has a text representation of `2021-11-15T10:05:32.0000000Z` | `($)StartedAt` is a variable of type [Nullable][]<[DateTimeOffset][]>. | +| [Ended At][EndedAt Property] | `($)EndedAt`, with value of [DateTimeOffset][] that has a text representation of `2021-11-15T10:06:12.0000000Z` | `($)EndedAt` is a variable of type [Nullable][]<[DateTimeOffset][]>. | + +#### Result + +Logging the event results in the following log being written: + +{{< highlight go "linenos=table,hl_lines=5 7-8 13-33,linenostart=1" >}} +{ + "@t":"2021-11-15T10:06:15.0000000Z", + "@mt":"{@Event}", + "Event":{ + "Type":"User Provisioning", + "Duration":{ + "StartedAt":"2021-11-15T10:05:32.0000000Z", + "EndedAt":"2021-11-15T10:06:12.0000000Z", + "InMs":40000, + "$type":"EventDurationDetails" + }, + "Details":{ + "Process":{ + "Provision New User":{ + "Stages":[ + { + "Configure Active Directory":{ + "Tasks":[ + "Add User to Azure Active Directory", + "Add User to On-Premise Active Directory" + ] + } + }, + { + "Configure Email":{ + "Tasks":[ + "Create Outlook Account", + "Create Default Signature" + ] + } + } + ] + } + }, + "Correlation":{ + "TraceId":null, + "SpanId":null, + "ParentSpanId":null, + "$type":"EventCorrelationDetails" + }, + "Service":{ + "Type":null, + "IpAddressOrFqdn":null, + "$type":"ServiceDetails" + }, + "$type":"StructuredEventLog" + } + } +} +{{< / highlight >}} + +For information about the format of the logs written, see [Anatomy of a Log][]. + +For information about where the logs are written to, see [Configuring Logging][]. + +*** + +## Properties + +### Event Details + +The [Event Details][EventDetails Property] to log. + +[Event Details][EventDetails Property] can be any object of any data type; it does not have to be a [String][]. Using a data type like a [Structure][] allows you to [create richer logs with a more defined format][Anatomy Of A Log]. This makes them easier to consume, process and query by other systems that consume logs, such as [Grafana][], [ElasticSearch][] and [Splunk][], which are commonly used for log analysis, reporting and dashboarding. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)EventDetails` with no value | + +### Event Type + +[Event Type][EventType Property] can be specified to define the type of event being logged. + +[Event Type][EventType Property] is a free format text property. If left blank, `null`, or empty (i.e. `""`) it will default to `Cortex.Blocks.Logs.LogEvent.LogEventBlock`. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `null`) | + +### Event Severity + +[Event Severity][EventSeverity Property] can be specified to define the severity of the event being logged. + +[Event Severity][EventSeverity Property] can be any of the following predefined values: + +* `EventSeverity.Verbose` - Logs that contain the most detailed messages. These messages may contain sensitive application data. These logs should never be enabled in a production environment. +* `EventSeverity.Debug` - Logs that are used for interactive investigation during development. These logs should primarily contain information useful for debugging and have no long-term value. +* `EventSeverity.Information` - Logs that track the general path of the flow execution. These logs should have long-term value. +* `EventSeverity.Warning` - Logs that highlight an abnormal or unexpected event in the path of the flow execution, but do not otherwise cause the flow execution to exit. +* `EventSeverity.Error` - Logs that highlight when the current flow execution exits due to an error. These should indicate a failure in the current flow execution, not a service-wide or process-wide failure. +* `EventSeverity.Fatal` - Logs that describe an unrecoverable service or process error, or a catastrophic failure that requires immediate attention. + +[Event Severity][EventSeverity Property] can also be left blank or set to `null`, in which case it will default to `EventSeverity.Information`. + +Logs with an [Event Severity][EventSeverity Property] of `EventSeverity.Information`, have the event severity omitted from the log that is written to the filesystem. This is to save disk space, as typically the highest volume of logs produced are Information logs. This cannot be changed and is a restriction of the underlying logging system used. All non-Information logs do include the event severity in the log that is written to the filesystem. + +| | | +|--------------------|---------------------------| +| Data Type | [Nullable][]<[EventSeverity][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `Information` | + +### Started At + +[Started At][StartedAt Property] can be specified to define the Date and Time the event being logged started. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +If [Started At][StartedAt Property] is left blank or set to `null`, a value of `null` will be logged. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Nullable][]<[DateTimeOffset][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `DateTimeOffset.UtcNow` | + +### Ended At + +[Ended At][EndedAt Property] can be specified to define the Date and Time the event being logged ended. + +Its text representation will be in the [ISO 8601 Standard][] (e.g. `2021-11-05T08:48:08.0307614+00:00`). + +If [Ended At][EndedAt Property] is left blank or set to `null`, a value of `null` will be logged. + +For more information about Date and Time, please see [Working with Date and Time][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Nullable][]<[DateTimeOffset][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `DateTimeOffset.UtcNow` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Event Severity][EventSeverity Property] is not one of the specified [EventSeverity][] types (e.g. `(EventSeverity)10`). | +| [PropertyNullException][] | Thrown when [Event Details][EventDetails Property] is `null`. | + +## Remarks + +### Configuring Logging + +Log settings exist for the following {{% ctx %}} Innovation Services: + +| Service | Default File Location | Description | +|----------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| `Execution Service` | `(Cortex.Blocks.Loops.ForEach.ForEachLoopBlock)
+ +## Description + +Loops through all items in the specified [Collection][Collection Property] (i.e. Lists, Dictionaries and Structures). + +The `"Index"` and `"Value"` of the current item are returned as properties of a [Structure][], which is saved to the [Current Iteration][CurrentIteration Property]. + +## Examples + +### Loop through all items in a list + +This example will loop through all items in `["Item1", "Item2", "Item3"]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection][Collection Property] | `($)Collection`, with value `["Item1", "Item2", "Item3"]` | `($)Collection` is a variable of type [IList][]<[String][]> | +| [Current Iteration][CurrentIteration Property] | `($)CurrentIteration`, with no value | `($)CurrentIteration` is a variable of type [Structure][] | + +#### Result + +Looping through all items in `["Item1", "Item2", "Item3"]` will result in `3` loops with `($)CurrentIteration` being updated to the following: + +1st loop + +```json +{ + "Index": 0, + "Value": "Item1" +} +``` + +2nd loop + +```json +{ + "Index": 1, + "Value": "Item2" +} +``` + +3rd loop + +```json +{ + "Index": 2, + "Value": "Item3" +} +``` + +*** + +### Loop through all items in a dictionary or structure + +This example will loop through all items in `{"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"}`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection][Collection Property] | `($)Collection`, with value `{"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"}` | `($)Collection` is a variable of type [IDictionary][]<[String][], [String][]> or [Structure][] | +| [Current Iteration][CurrentIteration Property] | `($)CurrentIteration`, with no value | `($)CurrentIteration` is a variable of type [Structure][] | + +#### Result + +Looping through all items in `{"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"}` will result in `3` loops with `($)CurrentIteration` being updated to the following: + +1st loop + +```json +{ + "Index": 0, + "Value": { + "Key": "Key1", + "Value": "Value1" + } +} +``` + +2nd loop + +```json +{ + "Index": 1, + "Value": { + "Key": "Key2", + "Value": "Value2" + } +} +``` + +3rd loop + +```json +{ + "Index": 2, + "Value": { + "Key": "Key3", + "Value": "Value3" + } +} +``` + +*** + +## Properties + +### Collection + +The [Collection][Collection Property] to loop through. + +If [Collection][Collection Property] is empty (i.e. contains no items), no looping will occur. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Collection` with no value | + +### Current Iteration + +The [Current Iteration][CurrentIteration Property] the looping is at. + +[Current Iteration][CurrentIteration Property] is set to a [Structure] on each loop, containing the current item's `"Index"` and `"Value"`. `"Index"` is set to `0` on the first loop, and on each subsequent loop is incremented by `1`. + +Looping will continue whilst `"Index"` is less than the number of items in [Collection][Collection Property], with the flow execution exiting via the block's right port (blue loop icon). + +Once `"Index"` equals the number of items in [Collection][Collection Property], looping stops, the flow execution exits via the block's bottom port (green tick) and [Current Iteration][CurrentIteration Property] is reset to an empty [Structure][]. + +If [Current Iteration][CurrentIteration Property] `"Index"` is modified during a loop, it will automatically be set back to its original value immediately before the next loop begins. + +| | | +|--------------------|---------------------------| +| Data Type | [Structure][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CurrentIteration` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Collection][Collection Property] is `null`. | + +## Remarks + +### Empty Collection + +If [Collection][Collection Property] is empty (i.e. contains no items), no looping will occur. + +[Collection Property]: {{< ref "#collection" >}} +[CurrentIteration Property]: {{< ref "#current-iteration" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/loops/for/_index.md b/content/en/docs/2023.9/Reference/Blocks/loops/for/_index.md new file mode 100644 index 000000000..98ef5db5a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/loops/for/_index.md @@ -0,0 +1,5 @@ +--- +title: "For Loop" +linkTitle: "For Loop" +description: "Blocks used to loop a specified number of times." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/loops/for/for-loop-block.md b/content/en/docs/2023.9/Reference/Blocks/loops/for/for-loop-block.md new file mode 100644 index 000000000..8653592ae --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/loops/for/for-loop-block.md @@ -0,0 +1,254 @@ +--- +title: "For Loop" +linkTitle: "For Loop" +description: "Loops a specified number of times based on a given start index, end index and increment." +--- + +{{< figure src="/blocks/loops-for-loop-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Loops.For.ForLoopBlock)
+ +## Description + +Loops a specified number of times based on a given [Start Index][StartIndex Property], [End Index][EndIndex Property] and [Increment][Increment Property]. + +## Examples + +### Loop between 0 and 2 incrementing by 1 + +This example will loop between `0` and `2` incrementing by `1` each loop. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `0` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `2` | `($)EndIndex` is a variable of type [Int32][] | +| [Increment][Increment Property] | `($)Increment`, with value `1` | `($)Increment` is a variable of type [Int32][] | +| [Current Index][CurrentIndex Property] | `($)CurrentIndex`, with value `0` | `($)CurrentIndex` is a variable of type [Int32][] that will be incremented by `($)Increment` each loop | + +#### Result + +Looping between `0` and `2` incrementing by `1` each loop will result in `3` loops with `($)CurrentIndex` being updated to the following: + +1st loop + +```json +0 +``` + +2nd loop + +```json +1 +``` + +3rd loop + +```json +2 +``` + +*** + +### Loop between 10 and 20 incrementing by 5 + +This example will loop between `10` and `20` incrementing by `5` each loop. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `10` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `20` | `($)EndIndex` is a variable of type [Int32][] | +| [Increment][Increment Property] | `($)Increment`, with value `5` | `($)Increment` is a variable of type [Int32][] | +| [Current Index][CurrentIndex Property] | `($)CurrentIndex`, with value `0` | `($)CurrentIndex` is a variable of type [Int32][] that will be incremented by `($)Increment` each loop | + +#### Result + +Looping between `10` and `20` incrementing by `5` each loop will result in `3` loops with `($)CurrentIndex` being updated to the following: + +1st loop + +```json +10 +``` + +2nd loop + +```json +15 +``` + +3rd loop + +```json +20 +``` + +*** + +### Loop between 20 and 10 incrementing by -5 + +This example will loop between `20` and `10` incrementing by `-5` each loop. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Start Index][StartIndex Property] | `($)StartIndex`, with value `20` | `($)StartIndex` is a variable of type [Int32][] | +| [End Index][EndIndex Property] | `($)EndIndex`, with value `10` | `($)EndIndex` is a variable of type [Int32][] | +| [Increment][Increment Property] | `($)Increment`, with value `-5` | `($)Increment` is a variable of type [Int32][] | +| [Current Index][CurrentIndex Property] | `($)CurrentIndex`, with value `0` | `($)CurrentIndex` is a variable of type [Int32][] that will be incremented by `($)Increment` each loop | + +#### Result + +Looping between `20` and `10` incrementing by `-5` each loop will result in `3` loops with `($)CurrentIndex` being updated to the following: + +1st loop + +```json +20 +``` + +2nd loop + +```json +15 +``` + +3rd loop + +```json +10 +``` + +*** + +## Properties + +### Start Index + +The [Start Index][StartIndex Property] the looping will start at. This is an inclusive index, which means the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### End Index + +The [End Index][EndIndex Property] the looping will end at. This is an inclusive index, which means the specified index will be included. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Increment + +The [Increment][Increment Property] to be added to [Current Index][CurrentIndex Property] every time the block loops. + +[Increment][Increment Property] can be: + +* A positive value if [Start Index][StartIndex Property] is less than [End Index][EndIndex Property]. +* A negative value if [Start Index][StartIndex Property] is greater than [End Index][EndIndex Property]. +* A positive or negative value if [Start Index][StartIndex Property] is equal to [End Index][EndIndex Property]. + +If any of the above are not `true` or [Increment][Increment Property] is `0` then an [InfiniteLoopException][] will be thrown the first time a flow execution executes this block. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `1` | + +### Current Index + +The [Current Index][CurrentIndex Property] the looping is at. + +[Current Index][CurrentIndex Property] initially gets set to the value of [Start Index][StartIndex Property] on the first loop, and on each subsequent loop is incremented by the value of [Increment][Increment Property]. + +If [Increment][Increment Property] is a positive value, the block will continue looping whilst [Current Index][CurrentIndex Property] is less than [End Index][EndIndex Property]; with the flow execution exiting via the block's right port (blue loop icon). + +If [Increment][Increment Property] is a negative value, the block will continue looping whilst [Current Index][CurrentIndex Property] is greater than [Start Index][StartIndex Property]; with the flow execution exiting via the block's right port (blue loop icon). + +When either of the above are not `true` the block stops looping, the flow execution exits via the block's bottom port (green tick) and [Current Index][CurrentIndex Property] is reset to `0` + +At this moment, there is a known limitation with [Current Index][CurrentIndex Property], which requires the variable used must have an [Int32][] value assigned to it before the block executes. If it does not then an [InvalidPropertyValueException][] will be thrown the first time a flow execution executes this block. + +For information about what an index is, please see [Indexes][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CurrentIndex` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InfiniteLoopException][] | Thrown when [Increment][Increment Property] is `0`. See [Increment Is Zero][]. | +| | Thrown when [Increment][Increment Property] has a positive value and [Start Index][StartIndex Property] is greater than [End Index][EndIndex Property]. See [Increment Is Positive][]. | +| | Thrown when [Increment][Increment Property] has a negative value and [Start Index][StartIndex Property] is less than [End Index][EndIndex Property]. See [Increment Is Negative][]. | +| [InvalidPropertyValueException][] | Thrown when [Current Index][CurrentIndex Property] does not have an [Int32][] value assigned to it before the block executes. See [Value Is Invalid][]. | + +## Remarks + +### Start Index and End Index are inclusive + +The [Start Index][StartIndex Property] and [End Index][EndIndex Property] properties are both inclusive [indexes][], which means those indexes will be included in the looping range (e.g. if [Start Index][StartIndex Property] is `0` and [End Index][EndIndex Property] is `1`, the block will loop `2` times). + +### Start Index greater than End Index + +[Start Index][StartIndex Property] can be greater than [End Index][EndIndex Property]. If this is the case, [Increment][Increment Property] must be a negative value. See [Example][StartIndexGreaterThanEndIndex Example] above. + +### Known Limitations + +The variable used for [Current Index][CurrentIndex Property] must have an [Int32][] value assigned to it before the block executes. If it does not then an [InvalidPropertyValueException][] will be thrown the first time a flow execution executes this block. + +[StartIndex Property]: {{< ref "#start-index" >}} +[EndIndex Property]: {{< ref "#end-index" >}} +[Increment Property]: {{< ref "#increment" >}} +[CurrentIndex Property]: {{< ref "#current-index" >}} + +[StartIndexGreaterThanEndIndex Example]: {{< ref "#loop-between-20-and-10-incrementing-by--5" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[InfiniteLoopException]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.MainDoc" >}} +[Increment Is Zero]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.IncrementIsZero" >}} +[Increment Is Negative]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.IncrementIsNegative" >}} +[Increment Is Positive]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.IncrementIsPositive" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/microsoft365/_index.md b/content/en/docs/2023.9/Reference/Blocks/microsoft365/_index.md new file mode 100644 index 000000000..1b6a801db --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/microsoft365/_index.md @@ -0,0 +1,5 @@ +--- +title: "Microsoft365" +linkTitle: "Microsoft365" +description: "Blocks related to working with Microsoft365." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/_index.md b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/_index.md new file mode 100644 index 000000000..2de0946a1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/_index.md @@ -0,0 +1,5 @@ +--- +title: "Outlook" +linkTitle: "Outlook" +description: "Blocks related to working with Outlook." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/_index.md b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Send Email" +linkTitle: "Send Email" +description: "Blocks related to sending Emails." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/send-email-using-microsoft365-block.md b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/send-email-using-microsoft365-block.md new file mode 100644 index 000000000..fff77124c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/microsoft365/outlook/send-email/send-email-using-microsoft365-block.md @@ -0,0 +1,278 @@ +--- +title: "Send Email Using Microsoft 365" +linkTitle: "Send Email Using Microsoft 365" +description: "Sends an email using the SMTP server hosted by Outlook." +--- + +{{< figure src="/blocks/microsoft365-send-email-using-microsoft365-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Microsoft365.Outlook.SendEmail.SendEmailUsingMicrosoft365Block)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Connects to the [SMTP][] server hosted by [Outlook][] using the specified [Credentials][Credentials Property], and sends an [Email Message][Email Message Property]. + +This block only supports authentication via OAuth (using [Microsoft365OAuthCredentials][] or [Microsoft365OAuthCertificateCredentials][]), to send an email using basic authentication, see [Send Email Using SMTP Server][]. + +## Examples + +### Sending an email using client credentials + +This example will send an email from `sender@outlook.com` to `recipient@outlook.com` using the [SMTP][] server hosted by [Outlook][]. + +The OAuth mechanism in this example uses client credentials. Therefore, for this example to work correctly, the [Credentials][Credentials Property] provided must be a [Microsoft365OAuthCredentials][]. + +For more information on: + +- What each of the properties in the [Microsoft365OAuthCredentials][] needs to be, see [Microsoft365OAuthCredentials][] +- How to set up an [Outlook][] account so that this authentication mechanism can be used, see [Setting up an Outlook account for OAuth authentication using client credentials][] + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Email Message][Email Message Property] | `($)EmailMessage` with value `{"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`(Cortex.Blocks.Object.ConvertObject.ConvertObjectToTextBlock`1)
+ +## Description + +Converts the given [Object][Object Property] to [Text][Text Property]. + +It does this by replacing all `{Property}` format parameters in the specified [Format Template][FormatTemplate Property] with the corresponding property value from the given [Object][Object Property]. + +An additional [Format Provider][FormatProvider Property] option can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting). + +## Examples + +### Convert Structure to Text + +This example will convert: + +```json +{ + "LastPaymentAmount": 99.99, + "PercentagePaidOff": 0.8000, + "PercentageRemaining": 0.2000, + "TotalPaidOff": 350.99, + "TotalRemaining": 40 +} +``` + +to text, based on the following format template: + +```json +"Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding." +``` + +The format parameter `{LastPaymentAmount:C2}` will display the `99.99` as U.S currency to two decimal places (i.e. `$99.99`): + +* `LastPaymentAmount` - is replaced by the value of the `"LastPaymentAmount"` property (i.e. `99.99`). +* `C` - indicates to include the currency symbol for the specified culture (i.e. `$`). +* `2` - indicates to format the value to two decimal places. + +The format parameter `{PercentagePaidOff:P0}` will display the `0.8000` as a percentage to zero decimal places (i.e. `80 %`): + +* `PercentagePaidOff` - is replaced by the value of the `"PercentagePaidOff"` (i.e. `0.8000`). +* `P` - indicates the value should be formatted as a percentage. +* `0` - indicates to format the percentage value to zero decimal places. + +The format parameter `{TotalRemaining:C2}` will display the `40` as U.S currency to two decimal places (i.e. `$40.00`): + +* `TotalRemaining` - is replaced by the value of the `"TotalRemaining"` property (i.e. `40`). +* `C` - indicates to include the currency symbol for the specified culture (i.e. `$`). +* `2` - indicates to format the value to two decimal places. + +For information about format templates and parameters, please see [Text Formatting][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Object][Object Property] | `($)Object`, with value `{"LastPaymentAmount":99.99, "PercentagePaidOff":0.8000, "PercentageRemaining":0.2000, "TotalPaidOff":350.99, "TotalRemaining":40}` | `($)Object` is a variable of type [Structure][] | +| [Format Template][FormatTemplate Property] | `($)FormatTemplate`, with value `"Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding."` | `($)FormatTemplate` is a variable of type [String][] | +| [Format Provider][FormatProvider Property] | `($)FormatProvider`, with value `new CultureInfo("en-US")` | `($)FormatProvider` is a variable of type [IFormatProvider][] | +| [Text][Text Property] | `($)Text`, with no value | `($)Text` is a variable that will be set to a [String][] value | + +#### Result + +Converting: + +```json +{ + "LastPaymentAmount": 99.99, + "PercentagePaidOff": 0.8000, + "PercentageRemaining": 0.2000, + "TotalPaidOff": 350.99, + "TotalRemaining": 40 +} +``` + +to text, based on the following format template: + +```json +"Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding." +``` + +results in the variable `($)Text` being updated to the following: + +```json +"Your latest payment of $99.99 has been received. You have paid 80 % of your total and have $40.00 outstanding." +``` + +*** + +## Properties + +### Object + +The [Object][Object Property] to convert to [Text][Text Property]. + +All `{Property}` format parameters which match a property name in the [Object][Object Property] will be replaced by that property's value. + +The values of matching properties do not have to be text, they can be any data type. Any non-text value will be converted to its text representation when it is replaced. + +For information about how types are converted to their text representation please see [Converting Objects To Text][]. + +| | | +|--------------------|---------------------------| +| Data Type | [TObject][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Object` with no value | + +### Format Template + +[Format Template][FormatTemplate Property] can be specified to define the format of the resultant [Text][Text Property]. + +All `{Property}` format parameters in [Format Template][FormatTemplate Property] will be replaced with the corresponding property value from the [Object][Object Property]. + +`{Property}` format parameters are case-sensitive, so must exactly match the property name in the [Object][Object Property]; those that do not will not be replaced. + +If [Format Template][FormatTemplate Property] is specified but does not contain any `{Property}` format parameters, nothing is replaced; [Text][Text Property] will be set to the value of [Format Template][FormatTemplate Property]. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), [Text][Text Property] will be set to the value of [Convert.ToString(Object, Format Provider)][Convert ToString]. + +For information about format templates and parameters, please see [Text Formatting][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Format Provider + +[Format Provider][FormatProvider Property] can be specified to define the cultural rules used to control the formatting (e.g. `new CultureInfo("en-US")` will apply American English rules to the formatting.). + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +| | | +|--------------------|---------------------------| +| Data Type | [IFormatProvider][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `CultureInfo.InvariantCulture` | + +### Text + +The formatted [Text][Text Property] that results from replacing all `{Property}` format parameters in [Format Template][FormatTemplate Property] with their corresponding property value from the given [Object][Object Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [FormatException][] | Thrown when [Format Template][FormatTemplate Property] contains a format parameter that is invalid or not well-formed (e.g. `"Cost is {TotalCost:Q2}`, as `"Q"` is not a [valid format parameter][]). | +| [PropertyNullException][] | Thrown when [Object][Object Property] is `null`. | + +## Remarks + +### Text Formatting + +Please note that changes to operating system settings, could result in some of the examples above displaying different results. + +For information about format templates and parameters, please see [Text Formatting][]. + +### Null or Empty Format Template + +If [Format Template][FormatTemplate Property] is specified but does not contain any `{Property}` format parameters, nothing is replaced; [Text][Text Property] will be set to the value of [Format Template][FormatTemplate Property]. + +If [Format Template][FormatTemplate Property] is not specified, `null` or empty (i.e. `""`), [Text][Text Property] will be set to the value of [Convert.ToString(Object, Format Provider)][Convert ToString]. + +### Null Format Provider + +If [Format Provider][FormatProvider Property] is not specified or `null`, `CultureInfo.InvariantCulture` will be used; `CultureInfo.InvariantCulture` is associated with the English language but not with any country/region. For more information, please see [Invariant Culture rules][]. + +### Nested Properties + +Format parameters support nested properties, which means given an object like the following: + +```json +{ + "LastPaymentAmount": 99.99, + "PaidOff": { + "Percentage": 0.8000, + "Total": 350.99 + }, + "Remaining": { + "Remaining": 0.2000, + "Total": 40 + } +} +``` + +that nested property values such as PaidOff.Total can be accessed. This is done by using the following format parameter syntax: + +```json +"{PaidOff.Total}" +``` + +### Known Limitations + +Currently the block does not support indexing into properties (i.e. `ListProperty[0]` or `DictionaryProperty["key"]`). + +[Object Property]: {{< ref "#object" >}} +[FormatTemplate Property]: {{< ref "#format-template" >}} +[FormatProvider Property]: {{< ref "#format-provider" >}} +[Text Property]: {{< ref "#text" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[FormatException]: {{< url path="MSDocs.DotNet.Api.System.FormatException" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[Convert ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToStringObjectFormatProvider" >}} + +[Converting Objects To Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.ConvertingObjectsToText.MainDoc" >}} +[Invariant Culture rules]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.InvariantCulture.MainDoc" >}} +[Text Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.MainDoc" >}} +[Valid Format Parameter]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatTemplates" >}} + +[TObject]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[IFormatProvider]: {{< url path="Cortex.Reference.DataTypes.Text.IFormatProvider.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/_index.md b/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/_index.md new file mode 100644 index 000000000..88c2803c9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/_index.md @@ -0,0 +1,5 @@ +--- +title: "Copy Object" +linkTitle: "Copy Object" +description: "Copy an object." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/copy-object-block-1.md b/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/copy-object-block-1.md new file mode 100644 index 000000000..0e83fe42f --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/objects/copy-object/copy-object-block-1.md @@ -0,0 +1,112 @@ +--- +title: "Copy Object" +linkTitle: "Copy Object" +description: "Copies an Object." +--- + +{{< figure src="/blocks/objects-copy-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Objects.CopyObject.CopyObjectBlock`1)
+ +## Description + +Makes a [Copy][Copy Property] of an [Object][Object Property]. + +Any type of object can be copied, including Lists, Dictionaries, Structures etc. + +A deep copy will be performed, which means if the [Object][Object Property] contains other objects, they are also copied. This is as opposed to a shallow copy, which only makes a copy of the [Object][Object Property]; in a shallow copy contained objects are not copied, they are left as the original. + +## Examples + +### Copy a List + +This example will make a copy of `[[1, 2, 3], [4, 5, 6]]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Object][Object Property] | `($)Object`, with value `[[1, 2, 3], [4, 5, 6]]` | `($)Object` is a variable of type [List][]<[List][]<[Int32][]>> | +| [Copy][Copy Property] | `($)Copy`, with no value | `($)Copy` is a variable that will be set to the type of the item (i.e. [List][]<[List][]<[Int32][]>>) | + +#### Result + +Making a copy of `[[1, 2, 3], [4, 5, 6]]` results in the variable `($)Copy` being updated to the following: + +```json +[ + [ + 1, + 2, + 3 + ], + [ + 4, + 5, + 6 + ] +] +``` + +Note that `($)Copy` is an exact copy. If `($)Copy` has new items added to it, items updated in it, or items removed from it, the original that `($)Copy` was copied from will not be affected. + +*** + +## Properties + +### Object + +The [Object][Object Property] to make the [Copy][Copy Property] of. + +Any type of object can be copied, including Lists, Dictionaries, Structures etc. + +A deep copy will be performed, which means if the [Object][Object Property] contains other objects, they are also copied. This is as opposed to a shallow copy, which only makes a copy of the [Object][Object Property]; in a shallow copy contained objects are not copied, they are left as the original. + +| | | +|--------------------|---------------------------| +| Data Type | [TObject][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Object` with no value | + +### Copy + +The [Copy][Copy Property] of the [Object][Object Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TObject][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Copy` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Null Object + +If [Object][Object Property] is not provided or is set to `null`, [Copy][Copy Property] will be set to `null`. + +[Object Property]: {{< ref "#object" >}} +[Copy Property]: {{< ref "#copy" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TObject]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/_index.md new file mode 100644 index 000000000..d143d831b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/_index.md @@ -0,0 +1,5 @@ +--- +title: "Queues" +linkTitle: "Queues" +description: "Blocks related to working with Queues." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/_index.md new file mode 100644 index 000000000..1f22e687a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Dequeue Item(s)" +linkTitle: "Dequeue Item(s)" +description: "Removes and returns an item or multiple items from a queue." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-item-block-2.md b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-item-block-2.md new file mode 100644 index 000000000..3c937a715 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-item-block-2.md @@ -0,0 +1,155 @@ +--- +title: "Dequeue Item" +linkTitle: "Dequeue Item" +description: "Removes and returns the Item at the beginning of a Queue." +--- + +{{< figure src="/blocks/queues-dequeue-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.DequeueItem.DequeueItemBlock`2)
+ +## Description + +Removes and returns the [Item][Item Property] at the beginning of a [Queue][Queue Property]. + +## Examples + +### Dequeue an Item from a Queue containing Items with different priorities + +This example will dequeue an item from a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1`, `"Item 0"` with a priority of `0` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 0", "Priority": 0}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [String][]) | + +#### Result + +Dequeueing an item from `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 0", "Priority": 0}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Item` being updated to the following: + +```json +"Item -1" +``` + +and the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item 0", + "Priority": 0 + }, + { + "Item": "Item 1", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Dequeue an Item from a Queue containing Items with the same priority + +This example will dequeue an item from a [QueueWithPriority][]<[Int32][], [Int32][]> that contains `1` with a priority of `0`, `2` with a priority of `0` and `3` with a priority of `0`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": 1, "Priority": 0}, {"Item": 2, "Priority": 0}, {"Item": 3, "Priority": 0}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[Int32][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to the type of the item (i.e. [Int32]) | + +#### Result + +Dequeueing an item from `{"Items": [{"Item": 1, "Priority": 0}, {"Item": 2, "Priority": 0}, {"Item": 3, "Priority": 0}], "PriorityComparer": {}}` results in the variable `($)Item` being updated to the following: + +```json +1 +``` + +and the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": 2, + "Priority": 0 + }, + { + "Item": 3, + "Priority": 0 + } + ], + "PriorityComparer": {} +} +``` + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to dequeue an [Item][Item Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Item + +The [Item][Item Property] at the beginning of the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Item` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyEmptyException][] | Thrown when [Queue][Queue Property] contains no items.| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | + +## Remarks + +None + +[Queue Property]: {{< ref "#queue" >}} +[Item Property]: {{< ref "#item" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-items-block-2.md new file mode 100644 index 000000000..d296cd95c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/dequeue-item/dequeue-items-block-2.md @@ -0,0 +1,176 @@ +--- +title: "Dequeue Items" +linkTitle: "Dequeue Items" +description: "Removes and returns Items at the beginning of a Queue." +--- + +{{< figure src="/blocks/queues-dequeue-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.DequeueItem.DequeueItemsBlock`2)
+ +## Description + +Removes and returns [Items][Items Property] at the beginning of a [Queue][Queue Property]. + +Each item is removed and returned to [Items][Items Property] in the same order as they were in the [Queue][Queue Property]. + +## Examples + +### Dequeue Count of Items from a Queue containing items with different priorities + +This example will dequeue `2` items from a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1`, `"Item 0"` with a priority of `0` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 0", "Priority": 0}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Count][Count Property] | `($)Count`, with value `2` | `($)Count` is a variable of type [Int32][] | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to a [List][]<[String][]> value | + +#### Result + +Dequeueing `2` items from `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 0", "Priority": 0}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Items` being updated to the following: + +```json +["Item -1", "Item 0"] +``` + +and the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item 1", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Dequeue Count of Items from a Queue containing items with the same priority + +This example will dequeue `3` items from a [QueueWithPriority][]<[Int32][], [Int32][]> that contains `1` with a priority of `0`, `2` with a priority of `0`, `3` with a priority of `0` and `4` with a priority of `0`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": 1, "Priority": 0}, {"Item": 2, "Priority": 0}, {"Item": 3, "Priority": 0}, {"Item": 4, "Priority": 0}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[Int32][], [Int32][]> | +| [Count][Count Property] | `($)Count`, with value `3` | `($)Count` is a variable of type [Int32][] | +| [Items][Items Property] | `($)Items`, with no value | `($)Items` is a variable that will be set to a [List][]<[Int32][]> value | + +#### Result + +Dequeueing `3` items from `{"Items": [{"Item": 1, "Priority": 0}, {"Item": 2, "Priority": 0}, {"Item": 3, "Priority": 0}, {"Item" : 4, "Priority": 0}], "PriorityComparer": {}}` results in the variable `($)Items` being updated to the following: + +```json +[1, 2, 3] +``` + +and the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": 4, + "Priority": 0 + } + ], + "PriorityComparer": {} +} +``` + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to dequeue the [Items][Items Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Count + +The [Count][Count Property] of [Items][Items Property] to dequeue. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +### Items + +The [Items][Items Property] at the beginning of the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TItem][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyEmptyException][] | Thrown when [Queue][Queue Property] contains no items.| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Count][Count Property] is greater than the count of items in [Queue][Queue Property]. | + +## Remarks + +### Negative Count + +If [Count][Count Property] is negative, all items are dequeued from [Queue][Queue Property] to [Items][Items Property]. + +### Zero Count + +If [Count][Count Property] is `0`, no items are dequeued and [Items][Items Property] is set to an empty list (i.e. `[]`). + +[Queue Property]: {{< ref "#queue" >}} +[Count Property]: {{< ref "#count" >}} +[Items Property]: {{< ref "#items" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/_index.md new file mode 100644 index 000000000..a92a80839 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Enqueue Item(s)" +linkTitle: "Enqueue Item(s)" +description: "Add an item or multiple items to a queue." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-item-block-2.md b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-item-block-2.md new file mode 100644 index 000000000..95ae6861c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-item-block-2.md @@ -0,0 +1,211 @@ +--- +title: "Enqueue Item" +linkTitle: "Enqueue Item" +description: "Adds an Item to a Queue at the specified Priority." +--- + +{{< figure src="/blocks/queues-enqueue-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.EnqueueItem.EnqueueItemBlock`2)
+ +## Description + +Adds an [Item][Item Property] to a [Queue][Queue Property] at the specified [Priority][Priority Property]. + +## Examples + +### Enqueue an Item to an empty Queue + +This example will enqueue `"Some Value"` with a priority of `0` to an empty [QueueWithPriority][]<[String][], [Int32][]>. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with value `"Some Value"` | `($)Item` is a variable of type [String][] | +| [Priority][Priority Property] | `($)Priority`, with value `0` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"Some Value"` with priority `0` to `{"Items": [], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Some Value", + "Priority": 0 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Enqueue an Item to a Queue already containing Items + +This example will enqueue `"Some Value"` with a priority of `0` to a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with value `"Some Value"` | `($)Item` is a variable of type [String][] | +| [Priority][Priority Property] | `($)Priority`, with value `0` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"Some Value"` with priority `0` to `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item -1", + "Priority": -1 + }, + { + "Item": "Some Value", + "Priority": 0 + }, + { + "Item": "Item 1", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Enqueue an Item to a Queue with the same Priority as an existing Item + +This example will enqueue `"Some Value"` with a priority of `1` to a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with value `"Some Value"` | `($)Item` is a variable of type [String][] | +| [Priority][Priority Property] | `($)Priority`, with value `1` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"Some Value"` with priority `1` to `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item -1", + "Priority": -1 + }, + { + "Item": "Item 1", + "Priority": 1 + }, + { + "Item": "Some Value", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +As `"Some Value"` and `"Item 1"` have the same [Priority][Priority Property], they are put in the order that they were added to the [Queue][Queue Property], so `"Some Value"` is placed behind `"Item 1"`. + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to add the [Item][Item Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Item + +The [Item][Item Property] to be added to the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Item` with no value | + +### Priority + +The [Priority][Priority Property] of the [Item][Item Property] being added to the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TPriority][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | Defaults to `null` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [InvalidPropertyValueException][] | Thrown when [Item][Item Property] is `null` and [Queue][Queue Property] only accepts non-nullable value types. See [Value Is Invalid][]. | +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | + +## Remarks + +None + +[Queue Property]: {{< ref "#queue" >}} +[Item Property]: {{< ref "#item" >}} +[Priority Property]: {{< ref "#priority" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[default]: {{< url path="MSDocs.DotNet.Api.System.Comparer.Default" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-items-block-2.md new file mode 100644 index 000000000..982d82d43 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/enqueue-item/enqueue-items-block-2.md @@ -0,0 +1,240 @@ +--- +title: "Enqueue Items" +linkTitle: "Enqueue Items" +description: "Adds Items to a Queue at the specified Priority." +--- + +{{< figure src="/blocks/queues-enqueue-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.EnqueueItem.EnqueueItemsBlock`2)
+ +## Description + +Adds [Items][Items Property] to a [Queue][Queue Property] at the specified [Priority][Priority Property]. + +Each item is added to the [Queue][Queue Property] in the same order as they are in [Items][Items Property]. + +## Examples + +### Enqueue multiple Items to an empty Queue + +This example will enqueue `"a"`, `"b"` and `"c"` with a priority of `0` to an empty [QueueWithPriority][]<[String][], [Int32][]>. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Items][Items Property] | `($)Items`, with value `["a", "b", "c"]` | `($)Items` is a variable of type [List][]<[String][]> | +| [Priority][Priority Property] | `($)Priority`, with value `0` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"a"`, `"b"` and `"c"` with priority `0` to `{"Items": [], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "a", + "Priority": 0 + }, + { + "Item": "b", + "Priority": 0 + }, + { + "Item": "c", + "Priority": 0 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Enqueue multiple Items to a Queue already containing Items + +This example will enqueue `"a"`, `"b"` and `"c"` with a priority of `0` to a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Items][Items Property] | `($)Items`, with value `["a", "b", "c"]` | `($)Items` is a variable of type [List][]<[String][]> | +| [Priority][Priority Property] | `($)Priority`, with value `0` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"a"`, `"b"` and `"c"` with priority `0` to `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item -1", + "Priority": -1 + }, + { + "Item": "a", + "Priority": 0 + }, + { + "Item": "b", + "Priority": 0 + }, + { + "Item": "c", + "Priority": 0 + }, + { + "Item": "Item 1", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +*** + +### Enqueue multiple Items to a Queue with the same Priority as an existing Item + +This example will enqueue `"a"`, `"b"` and `"c"` with a priority of `1` to a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Items][Items Property] | `($)Items`, with value `["a", "b", "c"]` | `($)Items` is a variable of type [List][]<[String][]> | +| [Priority][Priority Property] | `($)Priority`, with value `1` | `($)Priority` is a variable of type [Int32][] | + +#### Result + +Adding `"a"`, `"b"` and `"c"` with priority `1` to `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Queue` being updated to the following: + +```json +{ + "Items": [ + { + "Item": "Item -1", + "Priority": -1 + }, + { + "Item": "Item 1", + "Priority": 1 + }, + { + "Item": "a", + "Priority": 1 + }, + { + "Item": "b", + "Priority": 1 + }, + { + "Item": "c", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +As the added values and `"Item 1"` have the same [Priority][Priority Property], they are put in the order that they were added to the [Queue][Queue Property], so `"a"`, `"b"` and `"c"` are placed behind `"Item 1"`. + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to add the [Items][Items Property] to. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Items + +The [Items][Items Property] to be added to the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumerable<TItem>][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Items` with no value | + +### Priority + +The [Priority][Priority Property] of the [Items][Items Property] being added to the [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [TPriority][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | Defaults to `null` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] or [Items][Items Property] is `null`. | + +## Remarks + +### Empty Items + +If [Items][Items Property] is empty (i.e. `[]`) there is nothing to add, so no operation is performed. + +[Queue Property]: {{< ref "#queue" >}} +[Items Property]: {{< ref "#items" >}} +[Priority Property]: {{< ref "#priority" >}} + +[Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[default]: {{< url path="MSDocs.DotNet.Api.System.Comparer.Default" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[CannotModifyReadOnlyListException]: {{< url path="Cortex.Reference.Exceptions.Lists.CannotModifyReadOnlyListException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} +[Value Is Invalid]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.ValueIsInvalid" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/get-count/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/get-count/_index.md new file mode 100644 index 000000000..2fb3d1df1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/get-count/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Count(s) of Items" +linkTitle: "Get Count(s) of Items" +description: "Get the count(s) of items in a queue." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/get-count/get-count-of-all-items-block-2.md b/content/en/docs/2023.9/Reference/Blocks/queues/get-count/get-count-of-all-items-block-2.md new file mode 100644 index 000000000..76ce2e0e9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/get-count/get-count-of-all-items-block-2.md @@ -0,0 +1,102 @@ +--- +title: "Get Count Of All Items" +linkTitle: "Get Count Of All Items" +description: "Gets the count of all items in a Queue." +--- + +{{< figure src="/blocks/queues-get-count-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.GetCount.GetCountOfAllItemsBlock`2)
+ +## Description + +Gets the [Count][Count Property] of all items in a [Queue][Queue Property]. + +## Examples + +### Get Count of all items in a Queue + +This example will get the count of all items in a [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` | `($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Count][Count Property] | `($)Count`, with no value | `($)Count` is a variable that will be set to an [Int32][] value | + +#### Result + +Getting the count of all items in `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Count` being updated to the following: + +```json +2 +``` + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to get the [Count][Count Property] of all items from. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Count + +The [Count][Count Property] of all items in [Queue][Queue Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Count` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | + +## Remarks + +### Empty List + +If [Queue][Queue Property] is empty (i.e. `{"Items": [], "PriorityComparer": {}}`), the variable specified in the [Count][Count Property] property is set to `0`. + +[Queue Property]: {{< ref "#queue" >}} +[Count Property]: {{< ref "#count" >}} + +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/_index.md new file mode 100644 index 000000000..1b7c59da4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Peek Item(s)" +linkTitle: "Peek Item(s)" +description: "Gets the item or multiple items at the beginning of a queue without removing them." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/peek-item-block.md b/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/peek-item-block.md new file mode 100644 index 000000000..91c121878 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/peek-item/peek-item-block.md @@ -0,0 +1,116 @@ +--- +title: "Peek Item" +linkTitle: "Peek Item" +description: "Gets the item at the beginning of a queue without removing it." +--- + +{{< figure src="/blocks/queues-peek-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.PeekItem.PeekItemBlock`2)
+ +## Description + +Gets the [Item][Item Property] at the beginning of a [Queue][queue property] without removing it. + +## Examples + +### Peek the Item at the beginning of the Queue + +This example will peek [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1` and returns the Item with the minimal priority. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` |`($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | +| [Item][Item Property] | `($)Item`, with no value | `($)Item` is a variable that will be set to type of the Item (i.e. [String][]) | + +#### Result + +Peeking `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in the variable `($)Item` being updated to: + +```json +"Item -1" +``` + +and `($)Queue` still has the value: + +```json +{ + "Items": [ + { + "Item": "Item -1", + "Priority": -1 + }, + { + "Item": "Item 1", + "Priority": 1 + } + ], + "PriorityComparer": {} +} +``` + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to peek from. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +### Item + +The [Item][Item Property] with minimal priority. + +| | | +|--------------------|---------------------------| +| Data Type | [TItem][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Item` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyEmptyException][] | Thrown when [Queue][Queue Property] contains no items.| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | + +## Remarks + +None + +[Queue Property]: {{< ref "#queue" >}} +[Item Property]: {{< ref "#item" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/_index.md b/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/_index.md new file mode 100644 index 000000000..0a570cc57 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/_index.md @@ -0,0 +1,5 @@ +--- +title: "Remove Item(s)" +linkTitle: "Remove Item(s)" +description: "Removes an item or multiple items from a queue." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/remove-all-items-block.md b/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/remove-all-items-block.md new file mode 100644 index 000000000..cb40c9be4 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/queues/remove-item/remove-all-items-block.md @@ -0,0 +1,86 @@ +--- +title: "Remove All Items" +linkTitle: "Remove All Items" +description: "Removes all items from a queue." +--- + +{{< figure src="/blocks/queues-remove-all-items-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Queues.RemoveItem.RemoveAllItemsBlock)
+ +## Description + +Removes all items from a [Queue][queue property]. + +## Examples + +### Remove all items from the Queue + +This example will remove all items from [QueueWithPriority][]<[String][], [Int32][]> that contains `"Item -1"` with a priority of `-1` and `"Item 1"` with a priority of `1`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Queue][Queue Property] | `($)Queue`, with value `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` |`($)Queue` is a variable of type [QueueWithPriority][]<[String][], [Int32][]> | + +#### Result + +Removing all items from `{"Items": [{"Item": "Item -1", "Priority": -1}, {"Item": "Item 1", "Priority": 1}], "PriorityComparer": {}}` results in `($)Queue` being updated to: + +```json +{ + "Items": [], + "PriorityComparer": {} +} +``` + +*** + +## Properties + +### Queue + +The [Queue][Queue Property] to remove all items from. + +| | | +|--------------------|---------------------------| +| Data Type | [QueueWithPriority][]<[TItem][], [TPriority][]> | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Queue` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Queue][Queue Property] is `null`. | + +## Remarks + +### Empty Queue + +If [Queue][Queue Property] is empty (i.e. `{"Items": [], "PriorityComparer": {}}`) there is nothing to remove, so no operation is performed. + +[Queue Property]: {{< ref "#queue" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/schedules/_index.md b/content/en/docs/2023.9/Reference/Blocks/schedules/_index.md new file mode 100644 index 000000000..4959fc9ea --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/schedules/_index.md @@ -0,0 +1,5 @@ +--- +title: "Schedules" +linkTitle: "Schedules" +description: "Blocks related to working with Schedules." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/_index.md b/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/_index.md new file mode 100644 index 000000000..2ac050e2b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wait For" +linkTitle: "Wait For" +description: "Wait for certain events to occur (i.e. a duration to pass)." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/wait-for-duration-block.md b/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/wait-for-duration-block.md new file mode 100644 index 000000000..5dfdae45a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/schedules/wait-for/wait-for-duration-block.md @@ -0,0 +1,90 @@ +--- +title: "Wait For Duration" +linkTitle: "Wait For Duration" +description: "Waits for a specified time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds)." +--- + +{{< figure src="/blocks/schedules-wait-for-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Schedules.WaitFor.WaitForDurationBlock)
+ +## Description + +Waits for a specified [Duration][Duration Property]. + +## Examples + +### Wait for duration + +This example will wait for `30` seconds. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Duration][Duration Property] | `($)Duration`, with value of `{"Years": 0, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 30, "Milliseconds": 0}` | `($)Duration` is a variable of type [TimePeriod][] | + +#### Result + +The block will wait for `30` seconds before completing, at which stage the flow execution will proceed to the next block. + +*** + +## Properties + +### Duration + +The [Duration][Duration Property] to wait for. + +[Duration][Duration Property] can have positive and negative components where components are: + +* Years +* Months +* Days +* Hours +* Minutes +* Seconds +* Milliseconds + +When waiting for [Duration][Duration Property], the block will calculate the date time to wait until by adding the [Duration][Duration Property] to the current date time. It will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds. + +When adding months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. adding one month onto `2021-01-31T23:59:59+00:00` will equate to `2021-02-28T23:59:59+00:00`). + +| | | +|--------------------|---------------------------| +| Data Type | [TimePeriod][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | Years: `0`(Cortex.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Connects to a host using the [Ssh Session Details][Ssh Session Details Property], and executes a [Command][Command Property], returning the [Response][Response Property] and [Ssh Logs][Ssh Logs Property]. + +[Close Session][Close Session Property] can be specified to choose whether the session on the host is closed or is kept open for use on subsequent Execute Ssh Command blocks. + +## Examples + +### Execute a Command using UserCredentials + +This example will execute a [Command][Command Property] on the server with the following details: + +- Host - `"localhost"` +- Port - `22` +- Domain - `"domain"` +- Username - `"username"` +- Password - `"password"` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Command][Command Property] | `($)Command` with value `"ipconfig"` | `($)Command` is a variable of type [EncryptableText][] | +| [Ssh Session Details][Ssh Session Details Property] | `($)SshSessionDetails` with value `{"Host": "localhost", "Port": 22, "Credentials": {"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}, "TerminalPrompt": "(.*(~(.*[\r\n]?)\$\|>))"}`(Cortex.Blocks.Tasks.CancelTask.CancelAllTasksBlock`2)
+ +## Description + +Cancels the execution of all [Tasks][Tasks Property] in a specified list. + +## Examples + +### Cancel a list of running Tasks + +This example will cancel the executions of all tasks in a list; the list contains two [IExecutionTasks][IExecutionTask] that represent asynchronous executions of other flows. Both [IExecutionTasks][IExecutionTask] represent a flow that waits for 5 seconds then sets an output variable `ResultVariable` to `"ResultValue"`. The [Cancel All Tasks][CancelAllTasks] block begins execution 1 second after the asynchronous flows have started, so the flows get cancelled before each `ResultVariable` is set. + +When the [Cancel All Tasks][CancelAllTasks] block begins, the [IExecutionTasks][IExecutionTask] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Tasks][Tasks Property] | `($)Tasks`, with value `[($)ExecutionTask1, ($)ExecutionTask2]` | `($)Tasks` is a variable of type [List][]<[IExecutionTask][]> | + +#### Result + +Cancelling all [IExecutionTasks][IExecutionTask] 1 second after they have started, results in the flows they represent being cancelled and the properties of each [IExecutionTask][IExecutionTask] in `($)Tasks` being updated to the following: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": true, + "IsCompleted": true, + "IsCompletedSuccessfully": false, + "IsFaulted": true, + "Status": "Cancelled", + "Exception": { + "Exception Type": "FlowExecutionStoppedException", + "Message": "Flow execution has been stopped!", + "FlowId": "00000000-0000-0000-0000-000000000000", + "ExecutionId": "00000000-0000-0000-0000-000000000000" + } +} +``` + +*** + +### Cancel a list of completed Tasks + +This example will cancel the executions of all tasks in a list; the list contains two [IExecutionTasks][IExecutionTask] that represent asynchronous executions of other flows. Both [IExecutionTasks][IExecutionTask] represent a flow that waits for 5 seconds then sets an output variable `ResultVariable` to `"ResultValue"`. The [Cancel All Tasks][CancelAllTasks] block begins execution 6 seconds after the asynchronous flows have started, so the flows complete and set their `ResultVariable` before they could be cancelled. + +When the [Cancel All Tasks][CancelAllTasks] block begins, the [IExecutionTasks][IExecutionTask] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Tasks][Tasks Property] | `($)Tasks`, with value `[($)ExecutionTask1, ($)ExecutionTask2]` | `($)Tasks` is a variable of type [List][]<[IExecutionTask][]> | + +#### Result + +Cancelling all [IExecutionTasks][IExecutionTask] has no effect as the flows they represent were completed and their properties remain unchanged. + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +## Properties + +### Tasks + +The list of Tasks to cancel. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[ITask][]<[TResult][]>> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Tasks` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyContainsNullItemException][] | Thrown when any Task in [Tasks][Tasks Property] is `null`.| +| [PropertyEmptyException][] | Thrown when [Tasks][Tasks Property] contains no items.| +| [PropertyNullException][] | Thrown when [Tasks][Tasks Property] is `null`.| + +## Remarks + +### Cancelling a Task That Has Already Been Cancelled + +If the Task being cancelled has already been cancelled, this block will do nothing and the status of the Task will remain `"Cancelled"`. + +### Cancelling a Task That Has Been Completed + +If the Task being cancelled has already been completed, this block will do nothing and the status of the Task will remain `"RanToCompletion"`. + +### Cancelling a Task That Has Thrown an Exception + +If the Task being cancelled has thrown an exception during execution, this block will do nothing and the status of the Task will remain `"Faulted"`. + +[Tasks Property]: {{< ref "#tasks" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[TTask]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TResult]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyContainsNullItemException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyContainsNullItemException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[CancelAllTasks]: {{< ref "#cancel-all-tasks" >}} +[RunFlowAsync]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} + + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/tasks/cancel-task/cancel-task-block-1.md b/content/en/docs/2023.9/Reference/Blocks/tasks/cancel-task/cancel-task-block-1.md new file mode 100644 index 000000000..2d0902c26 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/tasks/cancel-task/cancel-task-block-1.md @@ -0,0 +1,163 @@ +--- +title: "Cancel Task" +linkTitle: "Cancel Task" +description: "Cancels a Task." +--- + +{{< figure src="/blocks/tasks-cancel-task-block.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Tasks.CancelTask.CancelTaskBlock`1)
+ +## Description + +Cancels the execution of the specified [Task][Task Property]. + +## Examples + +### Cancel a running Task + +This example will cancel an [IExecutionTask][] that represents the asynchronous execution of another flow. The flow this [IExecutionTask][] represents waits for 5 seconds then sets an output variable `ResultVariable` to `"ResultValue"`. The [Cancel Task Block][CancelTask] begins execution 1 second after the asynchronous flow has started, so the flow gets cancelled before `ResultVariable` is set. + +When the [Cancel Task Block][CancelTask] begins, the [IExecutionTask][] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Task][Task Property] | `($)Task`, with a value that represents the asynchronous execution of another flow | `($)Task` is a variable of type [IExecutionTask][] | + +#### Result + +Cancelling the [IExecutionTask][] 1 second after it has started, results in the flow it represents being cancelled and the properties of `($)Task` being updated to the following: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": true, + "IsCompleted": true, + "IsCompletedSuccessfully": false, + "IsFaulted": true, + "Status": "Cancelled", + "Exception": { + "Exception Type": "FlowExecutionStoppedException", + "Message": "Flow execution has been stopped!", + "FlowId": "00000000-0000-0000-0000-000000000000", + "ExecutionId": "00000000-0000-0000-0000-000000000000" + } +} +``` + +*** + +### Cancel a completed Task + +This example will cancel an [IExecutionTask][] that represents the asynchronous execution of another flow. The flow this [IExecutionTask][] represents waits for 5 seconds then sets the output variable `ResultVariable` to `"ResultValue"`. The [Cancel Task Block][CancelTask] begins execution 6 seconds after the asynchronous flow has started, so the flow completes and sets `ResultVariable` before it could be cancelled. + +When the [Cancel Task Block][CancelTask] begins, the [IExecutionTask][] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Task][Task Property] | `($)Task`, with a value that represents the asynchronous execution of another flow | `($)Task` is a variable of type [IExecutionTask][] | + +#### Result + +Cancelling the [IExecutionTask][] has no effect as the flow it represents was completed and its properties remain unchanged. + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +## Properties + +### Task + +The [Task][Task Property] to cancel. + +| | | +|--------------------|---------------------------| +| Data Type | [ITask][]<[TResult][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Task` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Task][Task Property] is `null`.| + +## Remarks + +### Cancelling a Task That Has Already Been Cancelled + +If the [Task][Task Property] being cancelled has already been cancelled, this block will do nothing and the status of the [Task][Task Property] will remain `"Cancelled"`. + +### Cancelling a Task That Has Been Completed + +If the [Task][Task Property] being cancelled has already been completed, this block will do nothing and the status of the [Task][Task Property] will remain `"RanToCompletion"`. + +### Cancelling a Task That Has Thrown an Exception + +If the [Task][Task Property] being cancelled has thrown an exception during execution, this block will do nothing and the status of the [Task][Task Property] will remain `"Faulted"`. + +[Task Property]: {{< ref "#task" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[TResult]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[CancelTask]: {{< ref "#cancel-task" >}} +[RunFlowAsync]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/_index.md b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/_index.md new file mode 100644 index 000000000..0d2464a6d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wait For Task(s)" +linkTitle: "Wait For Task(s)" +description: "Wait for a task or multiple tasks." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-all-tasks-block-2.md b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-all-tasks-block-2.md new file mode 100644 index 000000000..87419b034 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-all-tasks-block-2.md @@ -0,0 +1,282 @@ +--- +title: "Wait For All Tasks" +linkTitle: "Wait For All Tasks" +description: "Waits for multiple Tasks to complete and returns their Results." +--- + +{{< figure src="/blocks/tasks-wait-for-task-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock`2)
+ +## Description + +Waits for all of the specified [Tasks][Tasks Property] to finish and returns a list of all [Results][Results Property]. + +## Examples + +### Wait for multiple running Tasks + +This example will wait for three instances of an [IExecutionTask][] that represent asynchronous executions of other flows. The flows that the [IExecutionTask][]'s represent waits for 2 seconds, 4 seconds and 6 seconds respectively and then sets the output variable `TimeWaited` equal to the amount of seconds the flow waited. The [Wait For All Tasks][] block begins execution 1 second after the asynchronous flows are started. + +When the [Wait For All Tasks][] block begins, the [IExecutionTask][]'s will have the following properties: + +```json + +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} + +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Tasks][Tasks Property] | `($)Tasks`, with value that represents a list of asynchronous executions of another flow | `($)Tasks` is a variable of type [IList][]<[IExecutionTask][]> | +| [Results][Results Property] | `($)Results`, with no value | `($)Results` is a variable of type [IList][]<[Structure][]> | + +#### Result + +Waiting for the [IExecutionTask][]'s 1 second after they have started, results in the execution containing the [Wait For All Tasks][] block to wait for all tasks to complete, pausing for 5 seconds and then the variable `($)Results` being updated to the following: + +```json +[ + { + "TimeWaited": 2 + }, + { + "TimeWaited": 4 + }, + { + "TimeWaited": 6 + } +] +``` + +After the [Wait For All Tasks][] block finishes, the tasks in `($)Tasks` will be in the following state: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +### Wait for multiple completed Tasks + +This example will wait for three instances of an [IExecutionTask][] that represent asynchronous executions of other flows. The flows that the [IExecutionTask][]'s represent waits for 2 seconds, 4 seconds and 6 seconds respectively and then sets the output variable `TimeWaited` equal to the amount of seconds the flow waited. The [Wait For All Tasks][] block begins execution 7 seconds after the asynchronous flows are started, therefore starting after all the executions have already completed. + +When the [Wait For All Tasks][] block begins, the [IExecutionTask][]'s will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Tasks][Tasks Property] | `($)Tasks`, with value that represents a list of asynchronous executions of another flow | `($)Tasks` is a variable of type [IList][]<[IExecutionTask][]> | +| [Results][Results Property] | `($)Results`, with no value | `($)Results` is a variable of type [IList][]<[Structure][]> | + +#### Result + +Waiting for the [IExecutionTask][]'s 7 seconds after they have started, results in the execution containing the [Wait For All Tasks][] block to not wait and the variable `($)Results` being immediately updated to the following: + +```json +[ + { + "TimeWaited": 2 + }, + { + "TimeWaited": 4 + }, + { + "TimeWaited": 6 + } +] +``` + +After the [Wait For All Tasks][] block finishes, the tasks in `($)Tasks` will remain unchanged: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +## Properties + +### Tasks + +The list of [Tasks][Tasks Property] being waited for. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[ITask][]<[TResult][]>> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Tasks` with no value | + +### Results + +The list of [Results][Results Property] of all the [Tasks][Tasks Property] being waited for. + +The order of the [Results][Results Property] in the list will match the order of the [Tasks][Tasks Property] (ie. The Result of the Task at index 0, will also be at index 0). + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[TResult][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Results` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Tasks][Tasks Property] is `null`. | +| [PropertyEmptyException][] | Thrown when [Tasks][Tasks Property] is empty. | +| [PropertyContainsNullItemException][] | Thrown when one or more items in the list of [Tasks][Tasks Property] is `null`. | +| [AggregateTaskException][] | Thrown when one or more items in [Tasks][Tasks Property] throws an exception. | + +## Remarks + +### Waiting for Tasks that have been cancelled + +If one or more tasks in the [Tasks][Tasks Property] being waited on has already been cancelled or is cancelled whilst being waited on, this block will wait until all [Tasks][Tasks Property] are complete, then throw an [AggregateTaskException][] containing the cancellation exception(s). Please see [Waiting for a Task that has thrown an exception][WaitingException Remark] for more details. + +### Waiting for a Task that has been completed + +If one or more tasks in the [Tasks][Tasks Property] being waited on has completed, this block will wait for all [Tasks][Tasks Property] to complete before returning the [Results][Results Property]. + +### Waiting for a Task that has thrown an exception + +If one or more tasks in the [Tasks][Tasks Property] being waited on has already thrown an exception during execution or throws an exception whilst being waited on, this block will wait until all [Tasks][Tasks Property] are complete, then throw an [AggregateTaskException][]. + +The [AggregateTaskException][] has the property [TaskExceptions][] of type [IDictionary][]<[Int32][],[Exception][]>. This property contains a list of all exceptions thrown by the tasks as index/exception pairs, mapping the exception thrown to the index of the task that threw it. + +Below is an example of the value of [TaskExceptions][] after the first and third tasks both threw a [FlowException][]: +```json +{ + "0": { + "Exception Type": "FlowException", + "Message": "This flow threw an exception.", + "HelpLink": "https://docs.wearecortex.com/docs/2023.5/reference/exceptions/flows/flow-exception" + }, + "2": { + "Exception Type": "FlowException", + "Message": "This flow threw an exception.", + "HelpLink": "https://docs.wearecortex.com/docs/2023.5/reference/exceptions/flows/flow-exception" + } +} +``` + +To get the [Results][Results Property] of the [Tasks][Tasks Property] that did not throw an exception, you would need to use another [Wait For All Tasks][] block to wait on only the tasks that didn't throw an exception. Below is example showing the simplist method of doing so: + +{{< figure src="/images/WaitForAllTasksExample.png" title="Example Flow For Getting Only Successful Results" >}} + +1. Wait For All Tasks Block + * This block waits for three execution tasks in the variable `Tasks` to complete. + * The first and third execution throw an exception. + * The block throws an [AggregateTaskException][]. + * See [Wait For All Tasks][] block. +2. Handle Block Exception Block + * This block handles the [AggregateTaskException][]. + * It saves the exception to the variable `AggregateTaskException`. + * See [Handle Block Exception][] block. +3. Remove Items At Indexes Block + * This block removes all items at specific indexes from a list. + * The indexes to be removed are the indexes of the tasks that threw an exception. + * The [List][] property is set to `Tasks`. + * The [Indexes][] property is set to `AggregateTaskException.TaskExceptions.Keys`. + * See [Remove Items At Indexes] block. +4. Wait For All Tasks Block + * This block waits on the new list of [Tasks][Tasks Property]. + * The list now only contains only one task, the previously second task, as it did not throw an exception. + * See [Wait For All Tasks][] block. +5. Workspace Block + * This workspace then uses the successful results for something. + * See [Workspace][] block. + +[Tasks Property]: {{< ref "#tasks" >}} +[Results Property]: {{< ref "#results" >}} +[WaitingException Remark]: {{< ref "#waiting-for-a-task-that-has-thrown-an-exception" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TResult]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} +[Handle Block Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockException.MainDoc" >}} +[Remove Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndexes.MainDoc" >}} +[Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.MainDoc" >}} + +[List]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndexes.List" >}} +[Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndexes.Indexes" >}} + +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyContainsNullItemException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyContainsNullItemException.MainDoc" >}} +[AggregateTaskException]: {{< url path="Cortex.Reference.Exceptions.Tasks.AggregateTaskException.MainDoc" >}} + +[TaskExceptions]: {{< url path="Cortex.Reference.Exceptions.Tasks.AggregateTaskException.TaskExceptions" >}} + +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[FlowException]: {{< url path="Cortex.Reference.Exceptions.Flows.FlowException.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-task-block-1.md b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-task-block-1.md new file mode 100644 index 000000000..1611fd4c6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/tasks/wait-for-task/wait-for-task-block-1.md @@ -0,0 +1,196 @@ +--- +title: "Wait For Task" +linkTitle: "Wait For Task" +description: "Waits for a Task to complete and returns the Result." +--- + +{{< figure src="/blocks/tasks-wait-for-task-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Tasks.WaitForTask.WaitForTaskBlock`1)
+ +## Description + +Waits for the specified [Task][Task Property] to finish and returns the [Result][Result Property] from the [Task][Task Property]. + +## Examples + +### Wait for a running Task + +This example will wait for an [IExecutionTask][] that represents the asynchronous execution of another flow. The flow this [IExecutionTask][] represents waits for 5 seconds and then sets the output variable `ResultVariable` to `"ResultValue"`. The [Wait For Task][] block begins execution 1 second after the asynchronous flow is started. + +When the [Wait For Task][] block begins, the [IExecutionTask][] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": false, + "IsCompletedSuccessfully": false, + "IsFaulted": false, + "Status": "Running", + "Exception": null +} + +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Task][Task Property] | `($)Task`, with value that represents the asynchronous execution of another flow | `($)Task` is a variable of type [IExecutionTask][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` is a variable of type [Structure][] | + +#### Result + +Waiting for the [IExecutionTask][] 1 second after it is started, results in the execution containing the [Wait For Task][] block to wait for the task to complete, pausing for 4 seconds and then the variable `($)Result` being updated to the following: + +```json +{ + "ResultVariable": "ResultValue" +} +``` + +After the [Wait For Task][] block finishes, the `($)Task` will be in the following state: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +### Wait for a completed Task + +This example will wait for an [IExecutionTask][] that represents the asynchronous execution of another flow. The flow this [IExecutionTask][] represents waits for 5 seconds and then sets the output variable `ResultVariable` to `"ResultValue"`. The [Wait For Task][] block begins execution 6 seconds after the asynchronous flow is started, therefore starting after the execution has already completed. + +When the [Wait For Task][] block begins, the [IExecutionTask][] will have the following properties: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Task][Task Property] | `($)Task`, with value that represents the asynchronous execution of another flow | `($)Task` is a variable of type [IExecutionTask][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` is a variable of type [Structure][] | + +#### Result + +Waiting for the [IExecutionTask][] 6 seconds after it is started, results in the execution containing the [Wait For Task][] block to not wait and the variable `($)Result` being immediately updated to the following: + +```json +{ + "ResultVariable": "ResultValue" +} +``` + +After the [Wait For Task][] block finishes, the `($)Task` will remain unchanged: + +```json +{ + "ExecutionId": "00000000-0000-0000-0000-000000000000", + "Id": "00000000-0000-0000-0000-000000000000", + "IsCancelled": false, + "IsCompleted": true, + "IsCompletedSuccessfully": true, + "IsFaulted": false, + "Status": "RanToCompletion", + "Exception": null +} +``` + +*** + +## Properties + +### Task + +The [Task][Task Property] being waited for. + +| | | +|--------------------|---------------------------| +| Data Type | [ITask][]<[TResult][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Task` with no value | + +### Result + +The [Result][Result Property] of the [Task][Task Property] being waited for. + +| | | +|--------------------|---------------------------| +| Data Type | [TResult][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Result` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Task][Task Property] is `null`. | + +## Remarks + +### Waiting for a Task that has been cancelled + +If the [Task][Task Property] being waited on has already been cancelled or is cancelled whilst being waited on, this block will re-throw the cancellation exception. + +### Waiting for a Task that has been completed + +If the [Task][Task Property] being waited on has completed, this block will not wait and immediately return the [Task][Task Property]'s result. + +### Waiting for a Task that has thrown an exception + +If the [Task][Task Property] being waited on has already thrown an exception during execution or throws an exception whilst being waited on, this block will re-throw the exception. + +[Task Property]: {{< ref "#task" >}} +[Result Property]: {{< ref "#result-2" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TResult]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/telnet/_index.md b/content/en/docs/2023.9/Reference/Blocks/telnet/_index.md new file mode 100644 index 000000000..35cb370dd --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/telnet/_index.md @@ -0,0 +1,5 @@ +--- +title: "Telnet" +linkTitle: "Telnet" +description: "Blocks related to working with Telnet." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/_index.md b/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/_index.md new file mode 100644 index 000000000..11e33bc25 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute Telnet Command" +linkTitle: "Execute Telnet Command" +description: "Blocks related to executing Telnet commands." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/execute-telnet-command-block.md b/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/execute-telnet-command-block.md new file mode 100644 index 000000000..7d9f06bc3 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/telnet/execute-telnet-command/execute-telnet-command-block.md @@ -0,0 +1,419 @@ +--- +title: "Execute Telnet Command" +linkTitle: "Execute Telnet Command" +description: "Executes a Telnet command on the specified host." +--- + +{{< figure src="/blocks/execute-telnet-command-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommandBlock)
+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future; this will include further examples and remarks.{{% /alert %}} + +## Description + +Connects to a host using the [Telnet Session Details][Telnet Session Details Property], and executes a [Command][Command Property], returning the [Response][Response Property] and [Telnet Logs][Telnet Logs Property]. + +[Close Session][Close Session Property] can be specified to choose whether the session on the [Host] is closed or is kept open for use on subsequent Execute Telnet Command blocks. + +## Examples + +### Execute a Command + +This example will execute a [Command][Command Property] on the server with the following details: + +- [Host] - `"localhost"` +- [Port] - `23` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Command][Command Property] | `($)Command` with value `"ipconfig"` | `($)Command` is a variable of type [EncryptableText][] | +| [Telnet Session Details][Telnet Session Details Property] | `($)TelnetSessionDetails` with value `{"Host": "localhost", "Port": 23, "TerminalPrompt": "(.*(~(.*[\r\n]?)\$\|>))"}`(Cortex.Blocks.Variables.SetVariable.SetVariableBlock`1)
+ +## Description + +Sets a [Variable][Variable Property] to a given [Value][Value Property]. + +Any type of [Value][Value Property] can be set, including Lists, Dictionaries, Structures etc. + +If a [Variable][Variable Property] is set to the [Value][Value Property] of another [Variable][Variable Property] that is a [Reference Type][Reference Types] then they will refer to the same instance. This means that if either [Variable][Variable Property] has new items added to it, items updated in it, or items removed from it, then both will be affected, please see [Reference Types][] for more information. + +If a [Variable][Variable Property] is set to the [Value][Value Property] of another [Variable][Variable Property] that is a [Value Type][Value Types] then they will refer to different instances. This means that if either [Variable][Variable Property] is updated, then only the updated variable will be affected, please see [Value Types][] for more information. + +## Examples + +### Setting a Variable + +This example will set a [Variable][Variable Property] to a list of `[[1, 2, 3], [4, 5, 6]]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | [Value][Value Property], with value `[[1, 2, 3], [4, 5, 6]]` | The [Value][Value Property] is of type [List][]<[List][]<[Int32][]>> | +| [Variable][Variable Property] | `($)Variable`, with no value | `($)Variable` is a variable that will be set to the type of the value (i.e. [List][]<[List][]<[Int32][]>>) | + +#### Result + +Setting `($)Variable` to `[[1, 2, 3], [4, 5, 6]]` results in the variable `($)Variable` being updated to the following: + +```json +[ + [ + 1, + 2, + 3 + ], + [ + 4, + 5, + 6 + ] +] +``` + +*** + +### Overwriting a Variable + +This example will overwrite an existing [Variable][Variable Property] that has the text value `"A text value"`, to a list value of `[1, 2, 3]`. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | [Value][Value Property], with value `[1, 2, 3]` | The [Value][Value Property] is of type [List][]<[Int32]> | +| [Variable][Variable Property] | `($)Variable`, with value `"A text value"` | `($)Variable` is a variable that will be set to the type of the value (i.e. [List][]<[Int32][]>) | + +#### Result + +Setting `($)Variable` to `[1, 2, 3]` results in the variable `($)Variable` being updated to the following: + +```json +[ + 1, + 2, + 3 +] +``` + +*** + +Note that `($)Variable` is overwritten, any data previously stored within the variable will be lost. + +### Overwriting a Variable Property + +This example will update the `Items` property within an existing [Variable][Variable Property] that has the text value `"A text value"`, to a list of `[1, 2, 3]`. + +`($)Variable` has an initial value of: + +```json +{ + "Items": "A text value", +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Value][Value Property] | [Value][Value Property], with value `[1, 2, 3]` | The [Value][Value Property] is of type [List][]<[Int32][]> | +| [Variable][Variable Property] | `($)Variable.Items`, with value `"A text value"` | `($)Variable.Items` is a property within variable that will be set to the type of the value (i.e. [List][]<[Int32][]>) | + +#### Result + +Setting the `($)Variable.Items` property to `[1, 2, 3]` results in the `($)Variable` being updated to the following: + +```json +{ + "Items": [ + 1, + 2, + 3 + ] +} +``` + +Note that `($)Variable.Items` is overwritten, any data previously stored within the property will be lost. + +*** + +## Properties + +### Value + +The [Value][Value Property] to set the [Variable][Variable Property] to. + +A [Variable][Variable Property] can be set to any type of object, including Lists, Dictionaries, Structures etc. + +| | | +|--------------------|---------------------------| +| Data Type | [TValue][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### Variable + +The [Variable][Variable Property] that will be set to the [Value][Value Property]. + +If a [Variable][Variable Property] is set to the [Value][Value Property] of another [Variable][Variable Property] that is a [Reference Type][Reference Types] then they will refer to the same instance. This means that if either [Variable][Variable Property] has new items added to it, items updated in it, or items removed from it, then both will be affected, please see [Reference Types][] for more information. + +If a [Variable][Variable Property] is set to the [Value][Value Property] of another [Variable][Variable Property] that is a [Value Type][Value Types] then they will refer to different instances. This means that if either [Variable][Variable Property] is updated, then only the updated variable will be affected, please see [Value Types][] for more information. + +| | | +|--------------------|---------------------------| +| Data Type | [TValue][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Variable` with no value | + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Initialising Variables + +If the Set Variable block is used to set a [Variable][Variable Property] that is not initialised, the [Variable][Variable Property] will be initialised with the given [Value][Value Property] when the block is run. + +### Overwriting Variables + +If the Set Variable block is used to set a [Variable][Variable Property] that is already initialised and has a [Value][Value Property], the [Variable][Variable Property] will be overwritten with the new [Value][Value Property] when the block is run. + +A property of a [Variable][Variable Property] can also be overwritten, instead of the whole object. This is shown in the example above, [Overwriting a Variable Property][] + +### Variable Scope + +Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace's scope are deleted. + +The Set Variable block can only set a [Variable][Variable Property] that is accessible from its scope. + +For information about variables and scope, please see [Variables][]. + +### Null Value + +If [Value][Value Property] is not provided or is set to null, [Variable][Variable Property] will be set to null. + +[Variable Property]: {{< ref "#variable" >}} +[Value Property]: {{< ref "#value" >}} +[Overwriting a Variable Property]: {{< ref "#overwriting-a-variable-property" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[TValue]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Reference Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.ReferenceTypes" >}} +[Value Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.ValueTypes" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/_index.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/_index.md new file mode 100644 index 000000000..02d2c9a3d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/_index.md @@ -0,0 +1,5 @@ +--- +title: "Workspaces" +linkTitle: "Workspaces" +description: "Blocks used to organise flows and group related logic and actions together." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/_index.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/_index.md new file mode 100644 index 000000000..fa6587356 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/_index.md @@ -0,0 +1,5 @@ +--- +title: "End Workspace" +linkTitle: "End Workspace" +description: "Blocks that indicate the end of a workspace." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/end-workspace-block.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/end-workspace-block.md new file mode 100644 index 000000000..49a390849 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/end-workspace/end-workspace-block.md @@ -0,0 +1,45 @@ +--- +title: "End Workspace" +linkTitle: "End Workspace" +description: "Indicates the end of a workspace." +--- + +{{< figure src="/blocks/workspaces-end-workspace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Workspaces.EndWorkspace.EndWorkspaceBlock)
+ +## Description + +Indicates the end of a workspace; when a flow execution reaches this block it will exit the workspace, and all variables declared in the [scope][WorkspaceScope] of the workspace are deleted. + +A workspace can contain any number of these blocks, and they can be placed anywhere in the workspace. + +The block has no block specific properties, but it does have the `Description` property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. + +A breakpoint can be added to this block when debugging. + +## Examples + +No examples for the block. + +## Properties + +No properties for the block, other than the `Description` property that is common to all blocks. + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Workspace Scope + +Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace's scope are deleted. + +For information about variables and scope, please see [Variables][]. + +[WorkspaceScope]: {{< ref "#workspace-scope" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/_index.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/_index.md new file mode 100644 index 000000000..8a383367c --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/_index.md @@ -0,0 +1,5 @@ +--- +title: "Start Workspace" +linkTitle: "Start Workspace" +description: "Blocks that indicate the start of a workspace." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/start-workspace-block.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/start-workspace-block.md new file mode 100644 index 000000000..dc9afff63 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/start-workspace/start-workspace-block.md @@ -0,0 +1,45 @@ +--- +title: "Start Workspace" +linkTitle: "Start Workspace" +description: "Indicates the start of a workspace." +--- + +{{< figure src="/blocks/workspaces-start-workspace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Workspaces.StartWorkspace.StartWorkspaceBlock)
+ +## Description + +Indicates the start of a workspace; when a flow execution reaches this block it will create a new [scope][WorkspaceScope] for the workspace. + +This is always the first block in a workspace. It cannot be deleted, and a workspace can only contain one of these blocks. + +The block has no block specific properties, but it does have the `Description` property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. + +A breakpoint can be added to this block when debugging. + +## Examples + +No examples for the block. + +## Properties + +No properties for the block, other than the `Description` property that is common to all blocks. + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Workspace Scope + +Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace's scope are deleted. + +For information about variables and scope, please see [Variables][]. + +[WorkspaceScope]: {{< ref "#workspace-scope" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/_index.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/_index.md new file mode 100644 index 000000000..09a5c0e9b --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/_index.md @@ -0,0 +1,5 @@ +--- +title: "Workspace" +linkTitle: "Workspace" +description: "Blocks that represent a new workspace." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/workspace-block.md b/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/workspace-block.md new file mode 100644 index 000000000..8771671f7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/workspaces/workspace/workspace-block.md @@ -0,0 +1,79 @@ +--- +title: "Workspace" +linkTitle: "Workspace" +description: "Represents a new workspace." +--- + +{{< figure src="/blocks/workspaces-workspace-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Workspaces.Workspace.WorkspaceBlock)
+ +## Description + +This block represents a new workspace; when a flow execution reaches this block it will move to the [Start Workspace][] block within this block's workspace; each workspace has its own [scope][WorkspaceScope]. + +The [Workspace][] block can be used to organise block logic into smaller steps with distinct functions. When a new [Workspace][] block is placed on a flow, it will contain a [Start Workspace][] and [End Workspace][] block within its workspace. + +If a [Workspace][] block is copied and pasted its workspace is also copied, along with all blocks and variables within its [scope][WorkspaceScope]. + +The block has no block specific properties, but it does have the `Description` property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. Any description given will become the name for this block's [scope][WorkspaceScope] + +A breakpoint can be added to this block when debugging. + +## Examples + +No examples for the block. + +## Properties + +No properties for the block, other than the `Description` property that is common to all blocks, and the `Block Timeout` property that is common to most blocks. + +## Exceptions + +No exceptions are thrown by the block. + +## Remarks + +### Block Restrictions + +A workspace can contain any number of blocks. The only restrictions within a workspace are that there can only be one [Start Workspace][] block and one [Handle Workspace Exception][] block within a workspace. + +Starting a flow that contains more than one of the restricted blocks within a workspace will cause a [Validation Error][Validation Errors] to occur. + +### Unhandled Exceptions + +If an exception thrown by a block is not handled by any connected [Handle Block Exception blocks][], it will be passed to the [Handle Workspace Exception][] block on the same workspace. + +If the workspace does not contain a [Handle Workspace Exception][] block it will be rethrown by the [Workspace][] block the workspace belongs to. + +This process repeats until: + +* The exception is handled, or +* The exception reaches the flow's top-level workspace, is not handled by any [Handle Block Exception blocks][] and the top-level workspace does not contain a [Handle Workspace Exception][] block. At this stage, the exception is handled by the flow's [Handle Flow Exception][] block. + +If an exception occurs within the workspace of the [Handle Flow Exception][] block and is not handled, the flow will end with a status of Error. + +{{< figure src="/images/flow-error-status.png" >}} + +For more information about chaining of exception handling blocks and passing of exceptions, please see [Exception Handling][]. + +### Workspace Scope + +Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace's scope are deleted. + +For information about variables and scope, please see [Variables][]. + +[WorkspaceScope]: {{< ref "#workspace-scope" >}} + +[Start Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.StartWorkspace.StartWorkspace.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} +[Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.MainDoc" >}} +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} + +[Exception Handling]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Validation Errors]: {{< url path="Cortex.Reference.Messages.Validation.Errors.MainDoc" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Blocks/xml/_index.md b/content/en/docs/2023.9/Reference/Blocks/xml/_index.md new file mode 100644 index 000000000..14b4020e2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/xml/_index.md @@ -0,0 +1,5 @@ +--- +title: "Xml" +linkTitle: "Xml" +description: "Blocks related to working with Xml." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/_index.md b/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/_index.md new file mode 100644 index 000000000..98cd5d6a2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/_index.md @@ -0,0 +1,5 @@ +--- +title: "Convert Xml" +linkTitle: "Convert Xml" +description: "Convert xml to and from other data types." +--- diff --git a/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md b/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md new file mode 100644 index 000000000..5a988f7c6 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md @@ -0,0 +1,368 @@ +--- +title: "Convert Structure To Xml" +linkTitle: "Convert Structure To Xml" +description: "Converts a Structure To Xml." +--- + +{{< figure src="/blocks/xml-convert-to-xml-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +(Cortex.Blocks.Xml.ConvertXml.ConvertStructureToXmlBlock)
+ +## Description + +Converts a [Structure][Structure Property] to [Xml][Xml Property]. + +Each top-level [Key][Keys] will be converted using the following rules: + +* [Keys][] become [Nodes][Xml Nodes] +* [Items][] become the values of the corresponding node. + +Each inner key will be converted using the following rules: + +* Inner keys become inner nodes within their parent node. +* Items of inner keys become the values of the corresponding inner nodes. + +For example: + +``` json +"topLevelNode": { + "innerNode" : "innerNodeValue" +} +``` + +will be converted into: + +``` xml +@"(Cortex.Blocks.Xml.ConvertXml.ConvertXmlToStructureBlock)
+ +## Description + +Converts [Xml][Xml Property] to a [Structure][Structure Property]. + +Each top-level [Node][Xml Nodes] will be converted using the following rules: + +* Node names become [Keys][] +* Node values become [Items][] + +Each inner [Node][Xml Nodes] will be converted using the following rules: + +* Inner node names become [Keys][] within the top-level node's [Item][Items] +* Inner node values become the corresponding [Item][Items] for their [Key][Keys] + +For example: + +``` xml +@"(Cortex.Exceptions.Common.Property.PropertyContainsNullItemException)
+ +## Description + +The exception thrown when a [property][] is provided with a value that contains at least one item that is `null`. + +## Reasons + +### Value Contains `null` item + +A `null` item is contained in the value that was provided for the [property][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'(Cortex.Exceptions.Common.Property.PropertyContainsNullOrEmptyItemException)
+ +## Description + +The exception thrown when a [property][] is provided with a value that contains at least one item that is either `null` or empty, but the item is required to have a value. + +## Reasons + +### Value Contains `null` or empty item + +A `null` or empty item is contained in the value that was provided for the [property][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'(Cortex.Exceptions.Common.Property.PropertyEmptyException)
+ +## Description + +The exception thrown when a [property][] is provided with an [empty][] value, but a non-empty value is required. + +## Reasons + +### Empty value + +An [empty][] value was provided for the [property][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'(Cortex.Exceptions.Common.Property.PropertyItemCountException)
+ +## Description + +The exception thrown when the values provided for two [properties][] are expected to contain the same number of items, but don't. + +## Reasons + +### Item Counts Are Different + +Values provided for two [properties][] are expected to contain the same number of items, but don't. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Invalid '(Cortex.Exceptions.Common.Property.PropertyNullException)
+ +## Description + +The exception thrown when a [property][] is provided with a `null` value, but a non-null value is required. + +## Reasons + +### Value Is `null` + +A `null` value was provided for the [property][] when a non-null was required. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'(Cortex.Exceptions.Common.Property.PropertyValueOutOfRangeException)
+ +## Description + +The exception thrown when a [property][] is provided with a value that falls outside its accepted range. + +There are multiple reasons that this exception can be thrown: + +* [Property Is Empty][] +* [Property Is Empty Or `null`][] +* [Property Is Invalid][] +* [Property Is Negative][] +* [Property Greater Than Maximum Value][] +* [Property Less Than Minimum Value][] + +## Reasons + +### Property Is Empty + +An operation such as getting, setting or removing one or more items from an empty collection [property][] was performed. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Invalid '(Cortex.Exceptions.Lists.CannotModifyReadOnlyListException)
+ +The exception thrown when trying to modify a read-only list. + +> Lists deriving from [IList][]<[T][]> have the option to be read-only. + +The format of the exception message is as follows: + +```json +"The value of '(Cortex.Exceptions.Lists.DuplicateValueException)
+ +TODO: The exception thrown when... + +The format of the exception message is as follows: + +```json +TODO: Format +``` + +## How to fix + +TODO: How to fix... diff --git a/content/en/docs/2023.9/Reference/Exceptions/Xml/_index.md b/content/en/docs/2023.9/Reference/Exceptions/Xml/_index.md new file mode 100644 index 000000000..02f0740d1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/Xml/_index.md @@ -0,0 +1,5 @@ +--- +title: "Xml" +linkTitle: "Xml" +description: "Exceptions related to Xml blocks." +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Exceptions/Xml/xml-serialization-exception.md b/content/en/docs/2023.9/Reference/Exceptions/Xml/xml-serialization-exception.md new file mode 100644 index 000000000..0dd0508b9 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/Xml/xml-serialization-exception.md @@ -0,0 +1,22 @@ +--- +title: "XmlSerializationException" +linkTitle: "XmlSerializationException" +description: "The exception thrown when an Xml Serialization errors occur." +--- + + +# {{% param title %}} + +(Cortex.Exceptions.Xml.XmlSerializationException)
+ +TODO: The exception thrown when... + +The format of the exception message is as follows: + +```json +TODO: Format +``` + +## How to fix + +TODO: How to fix... diff --git a/content/en/docs/2023.9/Reference/Exceptions/_index.md b/content/en/docs/2023.9/Reference/Exceptions/_index.md new file mode 100644 index 000000000..a86fc4ede --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/_index.md @@ -0,0 +1,6 @@ +--- +title: "Exceptions" +linkTitle: "Exceptions" +description: "This section includes all reference documentation for exceptions." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Exceptions/collections/_index.md b/content/en/docs/2023.9/Reference/Exceptions/collections/_index.md new file mode 100644 index 000000000..274cfc43a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/collections/_index.md @@ -0,0 +1,5 @@ +--- +title: "Collections" +linkTitle: "Collections" +description: "Exceptions related to Collections" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/collections/occurrence-not-present-exception.md b/content/en/docs/2023.9/Reference/Exceptions/collections/occurrence-not-present-exception.md new file mode 100644 index 000000000..64130fc9e --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/collections/occurrence-not-present-exception.md @@ -0,0 +1,22 @@ +--- +title: "OccurrenceNotPresentException" +linkTitle: "OccurrenceNotPresentException" +description: "The exception thrown when trying to get a specified occurrence of an item from a collection, or set a specified occurrence of an item in a collection." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Collections.OccurrenceNotPresentException)
+ +The exception thrown when trying to get a specified occurrence of an item from a collection, or set a specified occurrence of an item in a collection. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/concurrency/_index.md b/content/en/docs/2023.9/Reference/Exceptions/concurrency/_index.md new file mode 100644 index 000000000..664797ba5 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/concurrency/_index.md @@ -0,0 +1,5 @@ +--- +title: "Concurrency" +linkTitle: "Concurrency" +description: "Exceptions related to Concurrency" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/_index.md b/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/_index.md new file mode 100644 index 000000000..5d379dfd2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/_index.md @@ -0,0 +1,5 @@ +--- +title: "Semaphores" +linkTitle: "Semaphores" +description: "Exceptions related to Semaphores" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md b/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md new file mode 100644 index 000000000..8f8cc3ff7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md @@ -0,0 +1,199 @@ +--- +title: "SemaphoreCouldNotBeAcquiredException" +linkTitle: "SemaphoreCouldNotBeAcquiredException" +description: "The exception thrown when a block is unable to acquire a semaphore." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Concurrency.SemaphoreCouldNotBeAcquiredException)
+ +## Description + +The exception thrown when a block is unable to acquire a [Semaphore][SemaphoreWhatIs]. + +## Reasons + +### Concurrency Limit reached + +The specified semaphore's [Concurrency Limit][SemaphoreConcurrencyLimit] has been reached, when the [Queue][SemaphoreQueue] property is set to `null`. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Requested semaphore '/(Cortex.Exceptions.DataStorage.DataStorageCollectionNotFoundException)
+ +## Description + +The exception thrown when an operation attempts to retrieve a [Data Storage Collection][] from a [Scope][] that does not exist in that [Scope][]. + +## Reasons + +### Data Storage Collection Could Not Be Found + +The key could not be found on the provided [Data Storage Collection][] could not be found. + +#### Message Format + +```json +"The '(Cortex.Exceptions.DataStorage.KeyInDataStorageCollectionNotFoundException)
+ +## Description + +The exception thrown when an operation attempts to retrieve data from a [Data Storage Collection][] using a key that does not exist in that collection. + +## Reasons + +### Key Could Not Be Found in the Data Storage Collection + +The key could not be found in the [Data Storage Collection][] provided. + +#### Message Format + +```json +"The key(Cortex.Exceptions.Data.CommandException)
+ +Exception thrown when any command execution has resulted in an exception being thrown. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +TODO: This is an example of how we can do exceptions with categories and error codes + +| Category | Error Code | Notes | +|--------------------|--------------|------------------------------------------| +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | + +## BasicCredentials.AccessTokenUri + +### 300 + +#### How to fix + +TODO: + +### 301 + +#### How to fix + +TODO: + +### 302 + +#### How to fix + +TODO: \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Exceptions/data/invalid-connection-string-exception.md b/content/en/docs/2023.9/Reference/Exceptions/data/invalid-connection-string-exception.md new file mode 100644 index 000000000..5b15b32d1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/data/invalid-connection-string-exception.md @@ -0,0 +1,70 @@ +--- +title: "InvalidConnectionStringException" +linkTitle: "InvalidConnectionStringException" +description: "Exception thrown when an invalid connection string is used." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Data.InvalidConnectionStringException)
+ +Exception thrown when an invalid connection string is used. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +TODO: This is an example of how we can do exceptions with categories and error codes + +| Category | Error Code | Notes | +|--------------------|--------------|------------------------------------------| +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | + +## BasicCredentials.AccessTokenUri + +### 300 + +#### How to fix + +TODO: + +### 301 + +#### How to fix + +TODO: + +### 302 + +#### How to fix + +TODO: \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Exceptions/decisions/_index.md b/content/en/docs/2023.9/Reference/Exceptions/decisions/_index.md new file mode 100644 index 000000000..194a2d699 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/decisions/_index.md @@ -0,0 +1,5 @@ +--- +title: "Decisions" +linkTitle: "Decisions" +description: "Exceptions related to Decisions" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/decisions/property-not-nullable-exception.md b/content/en/docs/2023.9/Reference/Exceptions/decisions/property-not-nullable-exception.md new file mode 100644 index 000000000..ba5e9c6f7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/decisions/property-not-nullable-exception.md @@ -0,0 +1,70 @@ +--- +title: "PropertyNotNullableException" +linkTitle: "PropertyNotNullableException" +description: "The exception thrown when a property cannot accept a non-nullable value type." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Decisions.PropertyNotNullableException)
+ +The exception thrown when a property cannot accept a non-nullable value type. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +TODO: This is an example of how we can do exceptions with categories and error codes + +| Category | Error Code | Notes | +|--------------------|--------------|------------------------------------------| +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | +| BasicCredentials | 300 | Some notes | +| | 301 | Some notes | +| | 302 | Some notes | + +## BasicCredentials.AccessTokenUri + +### 300 + +#### How to fix + +TODO: + +### 301 + +#### How to fix + +TODO: + +### 302 + +#### How to fix + +TODO: \ No newline at end of file diff --git a/content/en/docs/2023.9/Reference/Exceptions/dictionaries/_index.md b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/_index.md new file mode 100644 index 000000000..603d2052d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/_index.md @@ -0,0 +1,5 @@ +--- +title: "Dictionaries" +linkTitle: "Dictionaries" +description: "Exceptions related to Dictionaries" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md new file mode 100644 index 000000000..9ba519550 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md @@ -0,0 +1,38 @@ +--- +title: "CannotModifyReadOnlyDictionaryException" +linkTitle: "CannotModifyReadOnlyDictionaryException" +description: "The exception thrown when trying to modify a read-only dictionary." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException)
+ +The exception thrown when trying to modify a read-only dictionary. + +> Dictionaries implementing [IDictionary][]<[TKey][], [TItem][]> have the option to be read-only. + +The format of the exception message is as follows: + +```json +"'(Cortex.Exceptions.Dictionaries.KeyNotPresentException)
+ +The exception thrown when trying to get an item from a dictionary, or set an item in a dictionary, with a key that is not present. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/dictionaries/key-present-exception.md b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/key-present-exception.md new file mode 100644 index 000000000..aaa5c47f2 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/key-present-exception.md @@ -0,0 +1,22 @@ +--- +title: "KeyPresentException" +linkTitle: "KeyPresentException" +description: "The exception thrown when trying to add an item to a dictionary with a key that is already present." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Dictionaries.KeyPresentException)
+ +The exception thrown when trying to add an item to a dictionary with a key that is already present. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md new file mode 100644 index 000000000..90d917fe8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md @@ -0,0 +1,22 @@ +--- +title: "KeysNotPresentException" +linkTitle: "KeysNotPresentException" +description: "The exception thrown when trying to get items from a dictionary, or set items in a dictionary, and one of the keys used to find the items is not present." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Dictionaries.KeysNotPresentException)
+ +The exception thrown when trying to get items from a dictionary, or set items in a dictionary, and one of the keys used to find the items is not present. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/email/_index.md b/content/en/docs/2023.9/Reference/Exceptions/email/_index.md new file mode 100644 index 000000000..02bf88c2a --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Email" +linkTitle: "Email" +description: "Exceptions related to Email" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/email/email-session-exception.md b/content/en/docs/2023.9/Reference/Exceptions/email/email-session-exception.md new file mode 100644 index 000000000..90b9c6a76 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/email/email-session-exception.md @@ -0,0 +1,323 @@ +--- +title: "EmailSessionException" +linkTitle: "EmailSessionException" +description: "The exception thrown when an issue occurs while opening a session with a mail server." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Email.EmailSessionException)
+ +## Description + +The exception thrown when an issue occurs while opening a session with a mail server. + +There are multiple reasons that this exception can be thrown: + +- [Invalid Port][InvalidPortProvided] +- [Invalid Host][InvalidHostProvided] +- [SSL Required][SslWrappedConnectionRequired] +- [SSL Unsupported][SslWrappedConnectionNotSupported] +- [Invalid User Credentials][InvalidUsernameAndPassword] +- [Invalid SSL Certificate][InvalidSslCertificate] +- [Invalid Gmail Client Credentials][InvalidClientCredentials] + +## Reasons + +### Invalid Port {#100} + +A [Category][] of `Socket` and an [Error Code][] of `100` indicates that the [Port][] provided in the [ServerDetails][] is invalid. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The connection attempt to 'Host' ('(Cortex.Exceptions.FilesAndFolders.InvalidFolderNameException)
+ +The exception thrown when specifying an invalid folder name. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md b/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md new file mode 100644 index 000000000..ebc02f06d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md @@ -0,0 +1,22 @@ +--- +title: "InvalidPathException" +linkTitle: "InvalidPathException" +description: "The exception thrown when a file or folder path is invalid." +--- + +# {{% param title %}} + +(Cortex.Exceptions.FilesAndFolders.InvalidPathException)
+ +The exception thrown when specifying an invalid file or folder path. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md b/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md new file mode 100644 index 000000000..269dffdfe --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md @@ -0,0 +1,62 @@ +--- +title: "OperationFailedException" +linkTitle: "OperationFailedException" +description: "The exception thrown when a file or folder operation failed for one or more paths." +--- + +# {{% param title %}} + +(Cortex.Exceptions.FilesAndFolders.OperationFailedException)
+ +The exception thrown when a file or folder operation failed for one or more paths. + +## Path Exceptions + +### PathDoesNotExist + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +TODO: + +#### Blocks that can throw this exception + +TODO: + +### PathTooLong + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +TODO: + +#### Blocks that can throw this exception + +TODO: + +## Indexes Of Duplicate Paths + +/// If any path in the specified filePaths is duplicated and no exception is thrown for that path, the block will only process the first occurrence of the path, skipping any other occurrences. + + /// If any path in the specified filePaths is duplicated and an exception occurs for that path an(Cortex.Exceptions.Flows.Blocks.BlockTimeoutException)
+ +## Description + +TODO + +## Reasons + +### Block Timeout Reached + +TODO + +#### Message Format + +TODO + +The format of the [Message][] is as follows: + +```json +"TODO: \r\nPlease click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +TODO + +Ensure the action that the block is taking is likely to complete within the given [TimePeriod][]. + +## Properties + +TODO + +### Exception Type + +The type of the exception (i.e. `BlockTimeoutException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +TODO + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +TODO + +If a block is at a point that cannot cancel, then it will cancel at the next available opportunity. + +## See Also + +TODO + +### Related Data Types + +TODO + +* [String][] +* [TimePeriod][] + +### Related Concepts + +TODO + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +TODO: Update list + +All Blocks except: + +* Flows + * [Start Flow][] + * [End Flow][] +* Schedules + * [Wait For Duration][] +* Workspaces + * [Start Workspace][] + * [End Workspace][] + +### External Documentation + +TODO + +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} + +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} + +[Start Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.StartWorkspace.StartWorkspace.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} + +[Message]: {{< ref "#message" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md b/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md new file mode 100644 index 000000000..34e49d971 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md @@ -0,0 +1,128 @@ +--- +title: "InvalidBlockTimeoutException" +linkTitle: "InvalidBlockTimeoutException" +description: "The exception thrown when a block timeout is invalid." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Flows.Blocks.InvalidBlockTimeoutException)
+ +## Description + +TODO + +## Reasons + +### Block Timeout Reached + +TODO + +#### Message Format + +TODO + +The format of the [Message][] is as follows: + +```json +"TODO: \r\nPlease click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +TODO + +Ensure the action that the block is taking is likely to complete within the given [TimePeriod][]. + +## Properties + +TODO + +### Exception Type + +The type of the exception (i.e. `InvalidBlockTimeoutException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +TODO + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +TODO + +If a block is at a point that cannot cancel, then it will cancel at the next available opportunity. + +## See Also + +TODO + +### Related Data Types + +TODO + +* [String][] +* [TimePeriod][] + +### Related Concepts + +TODO + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +TODO: Update list + +All Blocks except: + +* Flows + * [Start Flow][] + * [End Flow][] +* Schedules + * [Wait For Duration][] +* Workspaces + * [Start Workspace][] + * [End Workspace][] + +### External Documentation + +TODO + +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} + +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} + +[Start Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.StartWorkspace.StartWorkspace.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Message]: {{< ref "#message" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-property-value-exception.md b/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-property-value-exception.md new file mode 100644 index 000000000..1141eb770 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/blocks/invalid-property-value-exception.md @@ -0,0 +1,210 @@ +--- +title: "InvalidPropertyValueException" +linkTitle: "InvalidPropertyValueException" +description: "The exception thrown when a property is provided with an invalid value." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Flows.Blocks.InvalidPropertyValueException)
+ +## Description + +The exception thrown when a [property][] is provided with an invalid value. + +This exception wraps the [InnerException][] that occurred when the value provided for the [property][] was used. + +## Reasons + +### Value Is Invalid + +An invalid value was provided for the [property][] with the specified [PropertyId][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The value of the property could not be evaluated." +``` + +#### How to fix + +Provide a valid value for the [property][] with the specified [PropertyId][], as instructed by the [Message][]. + +More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the message of the [InnerException][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `InvalidPropertyValueException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception, the message will always be the same. More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the message of the [InnerException][]. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### PropertyId + +The Id of the [property][] that has been provided an invalid value. + +| | | +|-----------|----------| +| Data Type | [Guid][] | + +### InnerException + +The exception that occurred when the value provided for the [property][] was used. + +This may contain more information on why the value is invalid, or instruction on how to provide a valid value in its message. + +| | | +|-----------|---------------| +| Data Type | [Exception][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, only the [PropertyId][] has been included in the exception. In future, we will look to include the name and Id of the [block][], the name and value of the [property][], as well as allowing the exception to contain a link to take you directly to the offending value. + +## See Also + +### Related Data Types + +* [String][] +* [Guid][] +* [Exception][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +* Dictionaries + * [Add Item With Key][] + * [Contains Item With Key And Value][] + * [Contains Item With Value][] + * [Get Count Of Items With Value][] + * [Remove Item With Value][] + * [Remove Items With Value][] + * [Set All Items][] + * [Set Item With Key][] + * [Set Item With Value][] + * [Set Items With Key][] + * [Set Items With Value][] +* Files & Folders + * [Read All Lines][] + * [Read All Text][] + * [Search File][] + * [Search Files][] + * [Write All Lines][] + * [Write All Text][] +* Lists + * [Add Item At Beginning][] + * [Add Item At End][] + * [Add Item At Index][] + * [Contains Item With Value][List Contains Item With Value] + * [Get Count Of Items With Value][List Get Count Of Items With Value] + * [Get Index Of Item With Value][] + * [Get Indexes Of Items With Value][] + * [Remove Item With Value][List Remove Item With Value] + * [Remove Items With Value][List Remove Items With Value] + * [Set Item At Beginning][] + * [Set Item At End][] + * [Set Item At Index][] + * [Set Item With Value][List Set Item With Value] + * [Set Items With Value][List Set Items With Value] +* Loops + * [For Loop][] +* Queues + * [Enqueue Item][] +* Text + * [Convert To Camel Case][] + * [Convert To Lower Case][] + * [Convert To Pascal Case][] + * [Convert To Title Case][] + * [Convert To Upper Case][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} +[PropertyId]: {{< ref "#propertyid" >}} +[InnerException]: {{< ref "#innerexception" >}} + +[Add Item With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.AddItem.AddItemWithKey.MainDoc" >}} +[Contains Item With Key And Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemWithKeyAndValue.MainDoc" >}} +[Contains Item With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemWithValue.MainDoc" >}} +[Get Count Of Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetCount.GetCountOfItemsWithValue.MainDoc" >}} +[Remove Item With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemWithValue.MainDoc" >}} +[Remove Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValue.MainDoc" >}} +[Set All Items]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetAllItems.MainDoc" >}} +[Set Item With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemWithKey.MainDoc" >}} +[Set Item With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemWithValue.MainDoc" >}} +[Set Items With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithKey.MainDoc" >}} +[Set Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithValue.MainDoc" >}} + +[Read All Lines]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.ReadFile.ReadAllLines.MainDoc" >}} +[Read All Text]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.ReadFile.ReadAllText.MainDoc" >}} +[Search File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.SearchFile.SearchFile.MainDoc" >}} +[Search Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.SearchFile.SearchFiles.MainDoc" >}} +[Write All Lines]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.WriteFile.WriteAllLines.MainDoc" >}} +[Write All Text]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.WriteFile.WriteAllText.MainDoc" >}} + +[Add Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemAtBeginning.MainDoc" >}} +[Add Item At End]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemAtEnd.MainDoc" >}} +[Add Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemAtIndex.MainDoc" >}} +[List Contains Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.ContainsItem.ContainsItemWithValue.MainDoc" >}} +[List Get Count Of Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.GetCount.GetCountOfItemsWithValue.MainDoc" >}} +[Get Index Of Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.GetIndex.GetIndexOfItemWithValue.MainDoc" >}} +[Get Indexes Of Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.GetIndex.GetIndexesOfItemsWithValue.MainDoc" >}} +[List Remove Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemWithValue.MainDoc" >}} +[List Remove Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsWithValue.MainDoc" >}} +[Set Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemAtBeginning.MainDoc" >}} +[Set Item At End]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemAtEnd.MainDoc" >}} +[Set Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemAtIndex.MainDoc" >}} +[List Set Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemWithValue.MainDoc" >}} +[List Set Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsWithValue.MainDoc" >}} + +[For Loop]: {{< url path="Cortex.Reference.Blocks.Loops.For.ForLoop.MainDoc" >}} + +[Enqueue Item]: {{< url path="Cortex.Reference.Blocks.Queues.EnqueueItem.EnqueueItemBlock.MainDoc" >}} + +[Convert To Camel Case]: {{< url path="Cortex.Reference.Blocks.Text.ConvertTo.ConvertToCamelCase.MainDoc" >}} +[Convert To Lower Case]: {{< url path="Cortex.Reference.Blocks.Text.ConvertTo.ConvertToLowerCase.MainDoc" >}} +[Convert To Pascal Case]: {{< url path="Cortex.Reference.Blocks.Text.ConvertTo.ConvertToPascalCase.MainDoc" >}} +[Convert To Title Case]: {{< url path="Cortex.Reference.Blocks.Text.ConvertTo.ConvertToTitleCase.MainDoc" >}} +[Convert To Upper Case]: {{< url path="Cortex.Reference.Blocks.Text.ConvertTo.ConvertToUpperCase.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/execution/_index.md b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/_index.md new file mode 100644 index 000000000..5ab4664a7 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execution" +linkTitle: "Execution" +description: "Exceptions related to the Execution of Flows" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/execution/flow-execution-cancelled-exception.md b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/flow-execution-cancelled-exception.md new file mode 100644 index 000000000..b3e981b39 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/flow-execution-cancelled-exception.md @@ -0,0 +1,99 @@ +--- +title: "FlowExecutionCancelledException" +linkTitle: "FlowExecutionCancelledException" +description: "The exception thrown when the child execution has been cancelled before execution has been completed." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Flows.Execution.FlowExecutionCancelledException)
+ +## Description + +The exception thrown when the child execution has been cancelled before the execution has been completed. + +## Reasons + +### The Child Execution Has Been Cancelled + +The child execution has been cancelled before the execution has completed. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The flow execution has been cancelled!" +``` + +#### How to fix + +Allow the execution to fully complete. + +## Properties + +### Exception Type + +The type of the exception (i.e. `FlowExecutionCancelledException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Flow Id + +The id of the flow where the execution has been cancelled. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### Execution Id + +The id of the execution that has been cancelled. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +## See Also + +### Related Data Types + +* [String][] +* [Guid][] + +### Related Concepts + +* [Exceptions][] +* [Executions][] +* [Flows][] + +### Related Blocks + +* [RunFlowAsync][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[RunFlowAsync]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/execution/invalid-input-variables-exception.md b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/invalid-input-variables-exception.md new file mode 100644 index 000000000..17bf5fe56 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/execution/invalid-input-variables-exception.md @@ -0,0 +1,140 @@ +--- +title: "InvalidInputVariablesException" +linkTitle: "InvalidInputVariablesException" +description: "The exception thrown when trying to run a flow with invalid input variables." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Flows.Execution.InvalidInputVariablesException)
+ +## Description + +The exception thrown when trying to run a [flow][] with invalid [Input Variables][]. + +## Reasons + +### Missing Input Variables + +This exception is thrown when a [flow][] is run and there are missing [Input Variables][]; any missing variables will be shown in the [InvalidVariableErrors][] property. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Couldn't initialize variable store because of invalid input variables." +``` + +#### How to fix + +Add the variables referenced in [InvalidVariableErrors][]. + +### Extra Input Variables + +This exception is thrown when a [flow][] is run and extra [Input Variables][] have been provided; any extra variables will be shown in the [InvalidVariableErrors][] property. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Couldn't initialize variable store because of invalid input variables." +``` + +#### How to fix + +Remove the variables referenced in [InvalidVariableErrors][]. + +### Input Variables of an Invalid Type + +This exception is thrown when a [flow][] is run and there are [Input Variables][] that are of an invalid type; any variables with an invalid type will be shown in the [InvalidVariableErrors][] property. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Couldn't initialize variable store because of invalid input variables." +``` + +#### How to fix + +Ensure the value provided for the variables referenced in [InvalidVariableErrors][] is either the same type as, or can be implicitly cast to the type defined in the default value for that [Input Variable][Input Variables]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `InvalidInputVariablesException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### InvalidVariableErrors + +A [List][]<InputVariableError> containing each invalid variable passed into the flow. + +| | | +|-----------|----------| +| Data Type | [List][]<InputVariableError> | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Data Types + +None + +### Related Concepts + +* [Flows][] +* [Variables][] +* [Exceptions][] + +### Related Blocks + +* Flows + * [Run Flow][] + * [Run Flow Async][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} +[InvalidVariableErrors]: {{< ref "#invalidvariableerrors" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} +[Run Flow Async]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Input Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/flows/flow-exception.md b/content/en/docs/2023.9/Reference/Exceptions/flows/flow-exception.md new file mode 100644 index 000000000..814b495f8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/flows/flow-exception.md @@ -0,0 +1,17 @@ +--- +title: "FlowException" +linkTitle: "FlowException" +description: "The exception thrown by the ThrowNewFlowException block." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Flows.FlowException)
+ +The exception thrown by the ThrowNewFlowException block. + +TODO: + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/http/_index.md b/content/en/docs/2023.9/Reference/Exceptions/http/_index.md new file mode 100644 index 000000000..9d4e1a2b8 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/http/_index.md @@ -0,0 +1,5 @@ +--- +title: "Http" +linkTitle: "Http" +description: "Exceptions related to HTTP" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/http/http-authorisation-exception.md b/content/en/docs/2023.9/Reference/Exceptions/http/http-authorisation-exception.md new file mode 100644 index 000000000..3dd10d9dd --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/http/http-authorisation-exception.md @@ -0,0 +1,11 @@ +--- +title: "HttpAuthorisationException" +linkTitle: "HttpAuthorisationException" +description: "The exception thrown when an issue occurs during the authorisation process when working with HTTP." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Http.HttpAuthorisationException)
+ +{{< workinprogress >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/http/invalid-request-exception.md b/content/en/docs/2023.9/Reference/Exceptions/http/invalid-request-exception.md new file mode 100644 index 000000000..1a5203a27 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/http/invalid-request-exception.md @@ -0,0 +1,11 @@ +--- +title: "InvalidRequestException" +linkTitle: "InvalidRequestException" +description: "The exception thrown when an issue occurs with a HTTP request." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Http.InvalidRequestException)
+ +{{< workinprogress >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/http/invalid-response-exception.md b/content/en/docs/2023.9/Reference/Exceptions/http/invalid-response-exception.md new file mode 100644 index 000000000..7893fe29f --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/http/invalid-response-exception.md @@ -0,0 +1,11 @@ +--- +title: "InvalidResponseException" +linkTitle: "InvalidResponseException" +description: "The exception thrown when an issue occurs with a HTTP response." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Http.InvalidResponseException)
+ +{{< workinprogress >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/impersonation/_index.md b/content/en/docs/2023.9/Reference/Exceptions/impersonation/_index.md new file mode 100644 index 000000000..87ab370f1 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/impersonation/_index.md @@ -0,0 +1,5 @@ +--- +title: "Impersonation" +linkTitle: "Impersonation" +description: "Exceptions related to Impersonation" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/impersonation/run-as-exception.md b/content/en/docs/2023.9/Reference/Exceptions/impersonation/run-as-exception.md new file mode 100644 index 000000000..f4b0eab52 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/impersonation/run-as-exception.md @@ -0,0 +1,136 @@ +--- +title: "RunAsException" +linkTitle: "RunAsException" +description: "The exception thrown when the provided UserCredentials has an invalid domain, username or password." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Impersonation.RunAsException)
+ +## Description + +The exception thrown when the provided [UserCredentials][] is invalid. + +## Reasons + +### Invalid Domain, Username Or Password {#1326} + +The [Run As Property][] has been provided a [UserCredentials][] object that has an invalid domain, username or password. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Impersonation failed with Win32 error code:(Cortex.Exceptions.Loops.InfiniteLoopException)
+ +## Description + +The exception thrown when an infinite loop can occur. + +There are multiple reasons that this exception can be thrown: + +* [Increment Is Zero][IncrementIsZero] +* [Increment Is Negative][IncrementIsNegative] +* [Increment Is Positive][IncrementIsPositive] + +## Reasons + +### Increment Is Zero {#100} + +A [Category][] of `"Increment"`and an [Error Code][] of `100` indicates that a zero increment value was provided. + +#### Message Format + +The format of the [Message][] can be one of the following: + +* If a zero value was provided and a negative value was expected + +```json +"The 'Increment' provided (0) causes an infinite loop. It must be a negative value. +Please click the HelpLink for more information on how to fix this." +``` + +* If a zero value was provided and a positive value was expected + +```json +"The 'Increment' provided (0) causes an infinite loop. It must be a positive value. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a negative or positive value for the increment as instructed by the [Message][]. + +### Increment Is Negative {#101} + +A [Category][] of `"Increment"`and an [Error Code][] of `101` indicates that a negative increment value was provided when a positive value was required. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The 'Increment' provided ({NegativeIncrement}) causes an infinite loop. It must be a positive value. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a positive value for the increment as instructed by the [Message][]. + +### Increment Is Positive {#102} + +A [Category][] of `"Increment"`and an [Error Code][] of `102` indicates that a positive increment value was provided when a negative value was required. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The 'Increment' provided ({PositiveIncrement}) causes an infinite loop. It must be a negative value. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a negative value for the increment as instructed by the [Message][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `InfiniteLoopException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Category + +The category of the exception, which is used to categorise an exception if there are multiple reasons that the exception can occur. + +For `InfiniteLoopException` the only category is `Increment`. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Error Code + +The error code for the exception, which is used to indicate the reason that the exception occurred, if there are multiple reasons that the exception can occur. + +For `InfiniteLoopException` there are three error codes: + +* [100][IncrementIsZero] - indicates the increment is zero, but should be either negative or positive +* [101][IncrementIsNegative] - indicates the increment is negative, but should be positive +* [102][IncrementIsPositive] - indicates the increment is positive, but should be negative + +| | | +|-----------|---------------------------| +| Data Type | [InfiniteLoopErrorCode][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [String][] +* [InfiniteLoopErrorCode][] + +### Related Concepts + +* [Exceptions][] +* [Working with Loops][] + +### Related Blocks + +* [For Loop][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} +[Category]: {{< ref "#category" >}} +[Error Code]: {{< ref "#error-code" >}} +[IncrementIsZero]: {{< ref "#100" >}} +[IncrementIsNegative]: {{< ref "#101" >}} +[IncrementIsPositive]: {{< ref "#102" >}} + +[For Loop]: {{< url path="Cortex.Reference.Blocks.Loops.For.ForLoop.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[InfiniteLoopErrorCode]: {{< url path="Cortex.Reference.DataTypes.Loops.InfiniteLoopErrorCode.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Working with Loops]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Loops.MainDoc" >}} diff --git a/content/en/docs/2023.9/Reference/Exceptions/powershell/_index.md b/content/en/docs/2023.9/Reference/Exceptions/powershell/_index.md new file mode 100644 index 000000000..be92b8a05 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/powershell/_index.md @@ -0,0 +1,5 @@ +--- +title: "PowerShell" +linkTitle: "PowerShell" +description: "Exceptions related to PowerShell" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-exception.md b/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-exception.md new file mode 100644 index 000000000..7815fba40 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-exception.md @@ -0,0 +1,22 @@ +--- +title: "PSException" +linkTitle: "PSException" +description: "Exception thrown when a terminating error occurs while executing scripts over WinRM." +--- + +# {{% param title %}} + +(Cortex.Exceptions.PowerShell.PSException)
+ +Exception thrown when a terminating error occurs while executing scripts over WinRM. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-remoting-exception.md b/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-remoting-exception.md new file mode 100644 index 000000000..d4ebe8c8d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/powershell/ps-remoting-exception.md @@ -0,0 +1,22 @@ +--- +title: "PSRemotingException" +linkTitle: "PSRemotingException" +description: "Exception thrown when access is denied to a host when attempting to executing scripts over WinRM." +--- + +# {{% param title %}} + +(Cortex.Exceptions.PowerShell.PSRemotingException)
+ +Exception thrown when access is denied to a host when attempting to executing scripts over WinRM. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/services/_index.md b/content/en/docs/2023.9/Reference/Exceptions/services/_index.md new file mode 100644 index 000000000..b6926475d --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/services/_index.md @@ -0,0 +1,5 @@ +--- +title: "Services" +linkTitle: "Services" +description: "Exceptions related to Services" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/services/service-does-not-exist-exception.md b/content/en/docs/2023.9/Reference/Exceptions/services/service-does-not-exist-exception.md new file mode 100644 index 000000000..4f95e6354 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/services/service-does-not-exist-exception.md @@ -0,0 +1,129 @@ +--- +title: "ServiceDoesNotExistException" +linkTitle: "ServiceDoesNotExistException" +description: "The exception thrown when a service does not exist." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Services.ServiceDoesNotExistException)
+ +## Description + +The exception thrown when either a [Core Service][] or [Execution Service][] does not exist. + +## Reasons + +### Service Does Not Exist + +The service does not exist. + +#### Message Format + +```json +"The '(Cortex.Exceptions.Services.ServiceUnavailableException)
+ +## Description + +The exception thrown when either a [Core Service][] or [Execution Service][] is unavailable. + +## Reasons + +### Service is Unavailable + +The service is either not running or unhealthy. + +#### Message Format + +```json +"The '(Cortex.Exceptions.Ssh.SshClientException)
+ +Exception thrown when an error occurs from the Sshclient object. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/ssh/ssh-response-exception.md b/content/en/docs/2023.9/Reference/Exceptions/ssh/ssh-response-exception.md new file mode 100644 index 000000000..4b598a0d0 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/ssh/ssh-response-exception.md @@ -0,0 +1,22 @@ +--- +title: "SshResponseException" +linkTitle: "SshResponseException" +description: "Exception thrown when an error occurs from the Ssh response." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Ssh.SshResponseException)
+ +Exception thrown when an error occurs from the Ssh response. + +The format of the exception message is as follows: + +```json +"TODO. +Please click the HelpLink for more information on how to fix this." +``` + +## How to fix + +TODO: diff --git a/content/en/docs/2023.9/Reference/Exceptions/tasks/_index.md b/content/en/docs/2023.9/Reference/Exceptions/tasks/_index.md new file mode 100644 index 000000000..476e38a46 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/tasks/_index.md @@ -0,0 +1,5 @@ +--- +title: "Tasks" +linkTitle: "Tasks" +description: "Exceptions related to issues with Tasks" +--- diff --git a/content/en/docs/2023.9/Reference/Exceptions/tasks/aggregate-task-exception.md b/content/en/docs/2023.9/Reference/Exceptions/tasks/aggregate-task-exception.md new file mode 100644 index 000000000..72576c963 --- /dev/null +++ b/content/en/docs/2023.9/Reference/Exceptions/tasks/aggregate-task-exception.md @@ -0,0 +1,123 @@ +--- +title: "AggregateTaskException" +linkTitle: "AggregateTaskException" +description: "The exception thrown when one or more tasks being waited on throw an exception." +--- + +# {{% param title %}} + +(Cortex.Exceptions.Tasks.AggregateTaskException)
+ +## Description + +The exception thrown when one or more tasks being waited on throw an exception. + +## Reasons + +### A task has thrown an exception + +One or more tasks being waited on has thrown an exception. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"One or more tasks that were being waited on threw an exception. Details of the exceptions can be found in the TaskExceptions property. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure that all tasks being waited on cannot throw any unhandled exceptions. + +For more information on how to get the results of the successful tasks, see [Waiting for a Task that has thrown an exception][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `AggregateTaskException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### TaskExceptions + +The [TaskExceptions][TaskExceptions Property] property is an [IDictionary][]<[Int32][],[Exception][]> of all exceptions thrown by the tasks as index/exception pairs, mapping the exception thrown to the index of the task that threw it. + +| | | +|-----------|------------| +| Data Type | [IDictionary][]<[Int32][],[Exception][]> | + +Below is an example of the value of [TaskExceptions][TaskExceptions Property] after the first and third tasks both throw a [FlowException][]: +```json +{ + "0": { + "Exception Type": "FlowException", + "Message": "This flow threw an exception.", + "HelpLink": "https://docs.wearecortex.com/docs/2023.5/reference/exceptions/flows/flow-exception" + }, + "2": { + "Exception Type": "FlowException", + "Message": "This flow threw an exception.", + "HelpLink": "https://docs.wearecortex.com/docs/2023.5/reference/exceptions/flows/flow-exception" + } +} +``` + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## See Also + +### Related Data Types + +* [Exception][] +* [FlowException][] +* [IDictionary(Cortex.Exceptions.Telnet.TelnetClientException)
+ +## Description + +The exception thrown when a Telnet Client (e.g. [Execute Telnet Command][]) is incorrectly configured. + +There are multiple reasons that this exception can be thrown: + +- [Invalid Host] +- [Invalid Port] +- [Invalid Terminal Prompt] +- [Invalid Configuration Settings] + +## Reasons + +### Invalid Host {#100} + +A [Category][] of `TelnetSessionDetails` and an [ErrorCode][] of `100` indicates that the [Host][] provided in the [TelnetSessionDetails][] is invalid. + +#### Message Format + +```json +"A connection could not be established between the server where the {{% ctx %}} Execution Service is running (\"