diff --git a/.github/workflows/checklink.yml b/.github/workflows/checklink.yml index d2d80131a..2cc329b30 100644 --- a/.github/workflows/checklink.yml +++ b/.github/workflows/checklink.yml @@ -40,7 +40,7 @@ jobs: config: .htmltest.yml - name: Archive htmltest results if: always() - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v3 # Note: Set ACTIONS_RUNTIME_TOKEN env variable to test with nektos/act with: name: htmltest-report diff --git a/assets/js/offline-search.js b/assets/js/offline-search.js index 6151d9b6e..6f99da65a 100644 --- a/assets/js/offline-search.js +++ b/assets/js/offline-search.js @@ -61,12 +61,14 @@ let docToAdd; if (searchPath !== undefined && doc.ref.startsWith(searchPath)) { docToAdd = doc; - } else if (searchPath === undefined) { docToAdd = doc; } - if (docToAdd) { + if (docToAdd + && docToAdd.ref !== undefined + && !docToAdd.ref.includes('/_shared/') + ) { this.add(doc); resultDetails.set(doc.ref, { @@ -150,11 +152,10 @@ ); const $searchResultBody = $('
').css({ - maxHeight: `calc(100vh - ${ - $targetSearchInput.offset().top - + maxHeight: `calc(100vh - ${$targetSearchInput.offset().top - $(window).scrollTop() + 180 - }px)`, + }px)`, overflowY: 'auto', }); $html.append($searchResultBody); diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index 7525c57f0..ae05029a6 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -3,9 +3,19 @@ // .td-content { + display: grid; + grid-template-columns: minmax(0, 1fr); + grid-row-gap: 8px; + row-gap: 8px; order: 1; - p, li, td { + .reading-time { + margin: 5px 0px; + } + + p, + li, + td { font-weight: $font-weight-body-text; } @@ -16,29 +26,50 @@ } p { - margin-bottom: 0.2rem; + margin-top: 0px; + margin-bottom: 0px; } - > h1 { + >h1 { font-weight: $font-weight-bold; - margin-bottom: 1rem; } - > h2 { - margin-bottom: 1rem; + >h2 { + margin-top: 10px; + margin-bottom: 10px; + padding-bottom: 8px; + border-bottom: 1px solid rgba(50, 50, 50, 0.1); + } + + >h2:not(:first-of-type) { + margin-top: 24px; + } + + >h2+h3 { + margin-top: 10px; } - > h2:not(:first-child) { - margin-top: 3rem; + >h3 { + margin-top: 24px; + margin-bottom: 8px; } - > h2 + h3 { - margin-top: 1rem; + h3+h4 { + margin-top: 10px; } - > h3, > h4, > h5, > h6 { - margin-bottom: 1rem; - margin-top: 2rem; + >h4 { + margin-top: 14px; + margin-bottom: 4px; + } + + h4+h5, h5+h6 { + margin-top: 5px; + } + + >h5, >h6 { + margin-top: 10px; + margin-bottom: 4px; } img { @@ -53,7 +84,7 @@ max-width: 90%; } - > table { + >table { @extend .table-striped; @extend .table-responsive; @@ -61,30 +92,46 @@ @extend .table; } - > blockquote { + >blockquote { padding: 0 0 0 1rem; margin-bottom: $spacer; color: $gray-600; border-left: 6px solid $secondary; } - > ul li, > ol li { + >ul { + margin-bottom: 0px; + } + + >ul li, + >ol li { margin-bottom: .25rem; - > table { + >table { @extend .table-striped; - + @extend .table-responsive; - + @extend .table; - } + } } strong { font-weight: $font-weight-bold; } - > pre, > .highlight, > .lead, > h1, > h2, > ul, > ol, > p, > blockquote, > dl dd, .footnotes, > .alert { + >pre, + >.highlight, + >.lead, + >h1, + >h2, + >ul, + >ol, + >p, + >blockquote, + >dl dd, + .footnotes, + >.alert { @extend .td-max-width-on-larger-screens; } @@ -93,8 +140,10 @@ margin-bottom: 1 * $spacer; } - .lead { - margin-bottom: 1.5rem; + .lead, .td-byline { + width: 100%; + max-width: 100%; + margin: 5px 0px !important; } span { @@ -103,23 +152,25 @@ color: black; padding: 0.18rem 0.45rem 0.18rem 0.45rem } + &.threshold-warning { - background-color: #FF9830; + background-color: #FF9830; color: black; - padding: 0.18rem 0.45rem 0.18rem 0.45rem + padding: 0.18rem 0.45rem 0.18rem 0.45rem } + &.threshold-critical { background-color: #F2495C; color: black; - padding: 0.18rem 0.45rem 0.18rem 0.45rem + padding: 0.18rem 0.45rem 0.18rem 0.45rem } } - > .footnotes { + >.footnotes { font-style: italic; } - > .youtube-video { + >.youtube-video { max-width: 640px; width: 100%; animation: fadeIn 2s; @@ -130,6 +181,12 @@ border-radius: 5px; } } + + br { + content: " "; + display: block; + margin-bottom: 5px; + } } .td-title { @@ -142,6 +199,11 @@ } @keyframes fadeIn { - 0% { opacity: 0; } - 100% { opacity: 1; } + 0% { + opacity: 0; + } + + 100% { + opacity: 1; + } } \ No newline at end of file diff --git a/assets/scss/_sidebar-tree.scss b/assets/scss/_sidebar-tree.scss index b82a981d4..62088a674 100644 --- a/assets/scss/_sidebar-tree.scss +++ b/assets/scss/_sidebar-tree.scss @@ -114,9 +114,9 @@ @include media-breakpoint-up(md) { @supports (position: sticky) { position: sticky; - top: 4rem; + top: 5.5rem; z-index: 10; - height: calc(100vh - 6rem); + height: calc(100vh - 5.5rem); } } diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 32108bc97..9c5947255 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -33,8 +33,13 @@ body { text-align: left; background-color: $white; + h1:first-of-type { + font-weight: 700 !important; + } + h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 { color: $ctx-blue; + font-weight: 600 !important; } .slogan { @@ -155,31 +160,28 @@ body { h2 { font-size: $h2-font-size !important; - font-weight: 600 !important; - margin: 2rem 0rem 0.5rem 0rem !important; max-width: 100% !important; } h3 { font-size: $h3-font-size !important; - font-weight: 600 !important; - margin: 1rem 0rem 0rem 0rem !important; - padding-bottom: 0.5rem; + opacity: .95; } h4 { font-size: $h4-font-size !important; - font-weight: 400 !important; - margin: 1rem 0rem 0.5rem 0rem !important; + opacity: .90; } h5 { font-size: $h5-font-size !important; + opacity: .85; } h6 { font-size: $h6-font-size !important; + opacity: .80; } p.namespace { diff --git a/assets/scss/main.scss b/assets/scss/main.scss index 3faf20607..7103f8837 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -33,24 +33,25 @@ // Adjust anchors vs the fixed menu. @include media-breakpoint-up(md) { - .td-offset-anchor:target { - display: block; - position: relative; - top: -4rem; - visibility: hidden; - } - h1[id]:before, - h2[id]:before, - h3[id]:before, - h4[id]:before, - h5[id]:before { + h1[id]:target, + h2[id]:target, + h3[id]:target, + h4[id]:target, + h5[id]:target { content: " "; - margin-top: -6rem; - height: 6rem; - visibility: hidden; + margin-top: -90px; + padding-top: 90px; } } + +.td-cover-block { + background-attachment: fixed; + background-position: center; + background-repeat: no-repeat; + background-size: cover; +} + @import "rtl/main"; @import "styles_project"; \ No newline at end of file diff --git a/config/_default/config.toml b/config/_default/config.toml index c9afd287c..8bacca8b8 100644 --- a/config/_default/config.toml +++ b/config/_default/config.toml @@ -83,7 +83,7 @@ section = ["HTML", "print"] [params] copyright = "We Are CORTEX is registered as CORTEX LTD" -privacy_policy = "https://www.wearecortex.com/policies/external-data-policy/" +privacy_policy = "https://www.wearecortex.com/external-data-policy/" # First one is picked as the Twitter card image if not set on page. # images = ["images/project-illustration.png"] @@ -175,7 +175,7 @@ enable = true # Legal info relevant links. These will show up on left side of footer. [[params.links.legal]] name = "Privacy Policy" - url = "https://www.wearecortex.com/policies/external-data-policy/" + url = "https://www.wearecortex.com/external-data-policy/" [[params.links.legal]] name = "Terms and Conditions" url = "https://www.wearecortex.com/terms/" @@ -200,15 +200,20 @@ enable = true [[menu.main]] identifier = 'documentation' name = 'Documentation' - url = '/docs/2024.7' + url = '/docs/2024.9' weight = 10 # Releases menu +[[params.versions]] + version = "2024.9" + url = "/docs/2024.9/" + dotNetVersion = "net-8.0" + latest = true + [[params.versions]] version = "2024.7" url = "/docs/2024.7/" dotNetVersion = "net-6.0" - latest = true [[params.versions]] version = "2024.5" diff --git a/content/en/blog/releases/2024.X/2024.7.md b/content/en/blog/releases/2024.X/2024.7.md index be77755dc..08ee71d65 100644 --- a/content/en/blog/releases/2024.X/2024.7.md +++ b/content/en/blog/releases/2024.X/2024.7.md @@ -79,20 +79,20 @@ Finally, the [Product Portal][] includes updates related to: | [{{% ctx %}} Blocks Package][Blocks] | 46.0.4.24340 | Yes | Major | Yes | Flows will need to be [upgraded][upgrade flows steps]

Compatibility Version: 31.24250 | | [{{% ctx %}} Interaction Portal][Interaction Portal] | 2.0.0.24340 | Yes | Major | Yes | The Interaction Portal flows will need to be [upgraded][upgrade flows steps] | | {{% ctx %}} App Server Install Scripts | 5.1.1.24340 | Yes | Patch | No | | -| {{% ctx %}} Web App Server Install Scripts | 10.1.0.24340 | Yes | Major | No | Major changes occurred between internal development releases, however, these changes are not breaking between 2024.5 and 2024.7 | +| {{% ctx %}} Web App Server Install Scripts | 8.0.0.24330 | Yes | Major | No | Major changes occurred between internal development releases, however, these changes are not breaking between 2024.5 and 2024.7 | +| {{% ctx %}} Upgrade Scripts | 1.2.0.24210 | Yes | Minor | N/A | | | {{% ctx %}} Licence Fingerprint Generator | 3.1.1.24250 | No | N/A | N/A | | | {{% ctx %}} Encryption Key Generator | 1.2.0.23470 | No | N/A | N/A | | | {{% ctx %}} Encryptor | 3.1.0.24330 | Yes | Minor | N/A | | | {{% ctx %}} Flows Upgrader | 1.2.1.24330 | Yes | Minor | N/A | | - - ### Features #### Performance ##### Reduced the number of license check calls +Previously, the [{{% ctx %}} Execution Service][] would request to the [{{% ctx %}} Licence Management Service][] whether the license was valid before every flow execution. Now, the [{{% ctx %}} Execution Service][] will only query the license on startup, license added, license removed, and license updated events. Previously, the [{{% ctx %}} Execution Service][] would request to the [{{% ctx %}} Licence Management Service][] whether the license was valid before every flow execution. Now, the [{{% ctx %}} Execution Service][] will only query the license on startup, license added, license removed, and license updated events. Affected Components: diff --git a/content/en/blog/releases/2024.X/2024.9.md b/content/en/blog/releases/2024.X/2024.9.md new file mode 100644 index 000000000..87de9aae1 --- /dev/null +++ b/content/en/blog/releases/2024.X/2024.9.md @@ -0,0 +1,634 @@ +--- +title: "2024.9" +linkTitle: "2024.9" +date: 2024-10-07 +author: Paul Arnold ([@paulmarnold](https://twitter.com/paulmarnold)) +--- + +## Summary + +The 2024.9 [Release][] is now available. + +## Download Artefacts + +Installation artefacts can be requested by raising a case in the [{{% ctx %}} Service Portal][]. + +## Release Notes + +### Overview + +2024.9 is the second [Release][] of the next generation of {{% ctx %}} and improves on the [2024.7][] release in the following areas: + +* Capability +* Observability +* Scalability +* Security +* Usability +* Third-Party Support +* Installation +* Upgrade +* Documentation + +This release introduces multiple new features to the {{% ctx %}} platform: + +* The concept of [Process and Activity][], which are types of [Flow][], has now been introduced to {{% ctx %}} Gateway. +* [Saving Output Properties to multiple variables][] is now supported. +* A new built-in [execution context variable][] has been added to the Flow Engine which contains the initiator. +* A new [Proxy for the {{% ctx %}} 7 Flow API][] has been added to the platform. + +[Observability][] has been improved by [adding logging to blocks that communicate with external systems][Logging added to blocks that communicate with external systems]. +\ +Optimisation to [Scalability][] has also been made by [reducing the total number of NServiceBus endpoints and RabbitMQ queues][Reduction of total number of NServiceBus endpoints and RabbitMQ queues]. +\ +We increased the [Security][] of the platform by: + +* [Upgrading the OpenSSL version][Upgrade OpenSSL] shipped with the platform. +* Added [Multi-domain certificates support][]. +* A [CortexManagementUser for RabbitMQ is now created during upgrade][New CortexManagementUser added to manage RabbitMQ queues]. +* [Server-side validation added to {{% ctx %}} Gateway API][] to prevent [Path Traversal][] attacks. +* Removal of the [refresh token cookie on sign out][remove refresh token cookie on sign out]. + +The [Usability][] of the platform has been improved by: + +* Renaming the [Flows Charm to Dev and changing the icon][Rename Flows Charm to Dev and change icon]. +* Renaming the [Settings Charm to Admin and changing the icon][Rename Settings Charm to Admin and change icon]. + +[Third-party Support][] has been improved by [upgrading the platform to .NET 8][Upgrade to .NET 8]. +\ +[Installation][] when [files are blocked by the operating system][Support installation when files are blocked by the operating system] due to the `Zone.Identifier` is now supported. +\ +The [Upgrade][] process has been improved by: + +* [Supporting upgrade when files are blocked by the operating system][Support upgrade when files are blocked by the operating system]. +* Upgrading the [Execution Service when the engine version is unchanged][Execution Service is upgraded when the engine version is unchanged]. +* [Handling of the Execution Services lifecycle events][]. + +Finally, the [Documentation][] includes updates related to: + +* New concepts such as [Process and Activity][Process and Activity Documentation] as well as [Decomposition of Output properties][]. +* [Preventing deadlocks when using semaphores][Prevent deadlocks when using semaphores]. +* [Updating screenshots][screenshots updated] to reflect the new branding. +* [Flow compatibility version][Flow compatibility version introduced] being added to the release notes. +* [General improvements to the documentation][]. + +### Components + +| Release Component | Version | Updated | Update Type | Breaking Change | Notes | +|--------------------------------------------------------------------------------|---------------|---------|---------------|-----------------|--------| +| [{{% ctx %}} Innovation Core Application][] | 53.0.0.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} API Gateway Service][] | 38.3.0.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Authorisation Service][] | 7.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Concurrency Management Service][] | 7.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Configuration Management Service][] | 7.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Data Storage Service][] | 9.0.13.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Execution Management Service][] | 7.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Licence Management Service][] | 7.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Listeners Service][] | 2.0.0.24430 | Yes | First Release | N/A | | +|     > [{{% ctx %}} Package Management Service][] | 11.0.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Provisioning Service][] | 13.1.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Scheduling Service][] | 7.0.8.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Triggers Service][] | 11.0.0.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +| [{{% ctx %}} Innovation Execution Application][] | 24.1.1.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +|     > [{{% ctx %}} Execution Service][] | 24.1.1.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the reduction of the total number of NServiceBus endpoints and RabbitMQ queues are [breaking][Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues] between 2024.7 and 2024.9 if upgraded on its own | +| [{{% ctx %}} Gateway][Gateway], including [{{% ctx %}} Studio][] | 12.3.2.24430 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the server-side validation of the APIs are [breaking][Breaking - Server-side validation added to {{% ctx %}} Gateway API] between 2024.7 and 2024.9 | +| [{{% ctx %}} Blocks Package][Blocks] | 48.2.0.24420 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the upgrade to .NET 8 and are [breaking][Breaking - Upgrade to .NET 8] between 2024.7 and 2024.9 | +| [{{% ctx %}} Interaction Portal][Interaction Portal] | 2.0.0.24340 | No | N/A | N/A | | +| {{% ctx %}} App Server Install Scripts | 5.2.3.24430 | Yes | Minor | N/A | | +| {{% ctx %}} Web App Server Install Scripts | 8.1.1.24420 | Yes | Patch | N/A | | +| {{% ctx %}} Upgrade Scripts | 1.2.8.24430 | Yes | Patch | N/A | | +| {{% ctx %}} Licence Fingerprint Generator | 4.1.0.24360 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the upgrade to .NET 8 and are [breaking][Breaking - Upgrade to .NET 8] between 2024.7 and 2024.9 | +| {{% ctx %}} Encryption Key Generator | 2.0.0.24350 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the upgrade to .NET 8 and are [breaking][Breaking - Upgrade to .NET 8] between 2024.7 and 2024.9 | +| {{% ctx %}} Encryptor | 3.1.0.24330 | No | N/A | N/A | | +| {{% ctx %}} Flows Upgrader | 2.0.0.24350 | Yes | Major | Yes | Major changes occurred between releases, these changes are related to the upgrade to .NET 8 and are [breaking][Breaking - Upgrade to .NET 8] between 2024.7 and 2024.9 | + +### Features + +#### Capability + +##### Process and Activity + +The [concept of Process and Activity][Process and Activity] has been introduced to the {{% ctx %}} Gateway. This allows for the creation of [Process][] and [Activity][] flows. +[Processes][Process] are a type of [Flow][] that can contain multiple [Activities][Activity] and are used to model high-level business processes. +[Activities][Activity] are a type of [Flow][] that can be used to model tasks or actions. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] +* [{{% ctx %}} Block Packages][Blocks] + +##### Saving Output Properties to multiple variables + +It is now possible to use the [Expression editor][] for output properties. +This supports a new [decomposition syntax][] allowing saving selected values from an output property to multiple variables. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] + +##### Execution context variable + +A new [built-in _executionContext variable][] is now exposed in [processes][process] and [activities][activity]. +The `_executionContext` variable contains the initiator of the flow execution, as well as an `Extensions` property that can be used to store additional information. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] + +##### Proxy for the {{% ctx %}} 7 Flow API + +A new proxy for the {{% ctx %}} 7 Flow [API][] has been added to simplify migrating to the platform. This allows for the execution of flows using the same [API][] as the one used in {{% ctx %}} 7. + +The [API][] includes the following endpoints: + +* Encrypt +* Run Flow +* Run Flow Asynchronously + +By default, the `Run Flow` and `Run Flow Asynchronously` endpoints will run the specified flow within the default package and version. +To run the flow in a different package and version, the following [APIs][API] have been added to configure mappings between FlowNames and specific package versions: + +* Get all mappings +* Add single mapping +* Remove single mapping +* Remove all mappings + +Affected Components: + +* [{{% ctx %}} Innovation Core Application][] + * [{{% ctx %}} API Gateway Service][] + * [{{% ctx %}} Listeners Service][] + * [{{% ctx %}} Triggers Service][] + +#### Observability + +##### Logging added to blocks that communicate with external systems + +Block logging has been added to blocks that communicate with external systems. +The following blocks and properties are logged: + +* [Execute Data Command][] + * [Command][DataCommand] +* [Execute HTTP Request][] + * [HTTPRequest][] + * [HTTPResponse][] +* [Execute SOAP Request][] + * [SOAPRequest][] + * [SOAPResponse][] +* [Execute Powershell Script][] + * [Script][] + * [Parameters][] + * [Outputs][] + * [Records][] +* [Execute SSH Command][] + * [Command][] + * [Response][] + * [SSH Logs][] + +Affected Components: + +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] +* [{{% ctx %}} Block Packages][Blocks] + +#### Scalability + +##### Reduction of total number of NServiceBus endpoints and RabbitMQ queues + +An exercise has been undertaken to reduce the total number of NServiceBus endpoints and RabbitMQ queues in the platform. +This has been achieved by consolidating the endpoints and queues where possible. + +Affected Components: + +* [{{% ctx %}} Innovation Core Application][] + * [{{% ctx %}} API Gateway Service][] + * [{{% ctx %}} Authorisation Service][] + * [{{% ctx %}} Concurrency Management Service][] + * [{{% ctx %}} Configuration Management Service][] + * [{{% ctx %}} Data Storage Service][] + * [{{% ctx %}} Execution Management Service][] + * [{{% ctx %}} Licence Management Service][] + * [{{% ctx %}} Package Management Service][] + * [{{% ctx %}} Provisioning Service][] + * [{{% ctx %}} Scheduling Service][] + * [{{% ctx %}} Triggers Service][] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] + +#### Security + +##### Upgrade OpenSSL + +The OpenSSL version shipped with the platform has been upgraded to the latest version. + +Affected Components: + +* {{% ctx %}} App Server Install Scripts +* {{% ctx %}} Web App Server Install Scripts + +##### Multi-domain certificates support + +Support for Multi Domain Certificates in HA deployment is now supported. + +Affected Components: + +* {{% ctx %}} App Server Install Scripts +* {{% ctx %}} Web App Server Install Scripts + +##### New CortexManagementUser added to manage RabbitMQ queues + +A new management user for RabbitMQ queues is now created when providing `RabbitMqManagementUser` and `RabbitMqManagementPassword` during installation or upgrade. + +Affected Components: + +* {{% ctx %}} App Server Install Scripts + +##### Server-side validation added to {{% ctx %}} Gateway API + +The {{% ctx %}} Gateway [API][] now includes server-side validation to prevent [Path Traversal][] attacks when creating new flows and groups. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] + +##### Remove refresh token cookie on sign out + +The refresh token cookie is now removed when a user signs out of {{% ctx %}} Gateway, preventing any further use of the token after the user has logged out. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] + +#### Usability + +##### Rename Flows Charm to Dev and change icon + +The Flows Charm has been renamed to Dev and the icon has been changed to reflect this. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] + +##### Rename Settings Charm to Admin and change icon + +The Settings Charm has been renamed to Admin and the icon has been changed to reflect this. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] + +#### Third-party Support + +##### Upgrade to .NET 8 + +The platform has been upgraded to [.NET 8][], allowing us to go to the latest version of [Service Fabric][]. +This was required as .NET 6 will be out of support in November. + +{{% alert title="Note" %}} +Upgrade excludes {{% ctx %}} Gateway as currently on .NET Framework 4.7.2 which is not compatible with .NET 8, and still under long term support. +{{% /alert %}} + +Affected Components: + +* [{{% ctx %}} Innovation Core Application][] + * [{{% ctx %}} API Gateway Service][] + * [{{% ctx %}} Authorisation Service][] + * [{{% ctx %}} Concurrency Management Service][] + * [{{% ctx %}} Configuration Management Service][] + * [{{% ctx %}} Data Storage Service][] + * [{{% ctx %}} Execution Management Service][] + * [{{% ctx %}} Licence Management Service][] + * [{{% ctx %}} Package Management Service][] + * [{{% ctx %}} Provisioning Service][] + * [{{% ctx %}} Scheduling Service][] + * [{{% ctx %}} Triggers Service][] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] +* [{{% ctx %}} Block Packages][Blocks] +* {{% ctx %}} App Server Install Scripts +* {{% ctx %}} Web App Server Install Scripts +* {{% ctx %}} Upgrade Scripts +* {{% ctx %}} Licence Fingerprint Generator +* {{% ctx %}} Encryption Key Generator +* {{% ctx %}} Flows Upgrader + +##### Upgrade to the latest version of Service Fabric + +The latest version of Service Fabric has been included in the artefacts. +During upgrade, the Service Fabric cluster version will be upgrade to the packaged version in the artefacts. + +Affected Components: + +* {{% ctx %}} Upgrade Scripts + +#### Installation + +##### Support installation when files are blocked by the operating system + +The installation scripts have been amended to unblock files before running if the operating system has files being blocked by `Zone.Identifier`. + +{{% alert title="Note" %}} +`Zone.Identifier` is a file property that indicates a file was downloaded from the internet and is potentially unsafe. Windows uses this property as a protection feature. +{{% /alert %}} + +Affected Components: + +* {{% ctx %}} App Server Install Scripts +* {{% ctx %}} Web App Server Install Scripts + +#### Upgrade + +##### Support upgrade when files are blocked by the operating system + +The upgrade scripts have been amended to unblock files before running if the operating system has files being blocked by `Zone.Identifier`. + +{{% alert title="Note" %}} +`Zone.Identifier` is a file property that indicates a file was downloaded from the internet and is potentially unsafe. Windows uses this property as a protection feature. +{{% /alert %}} + +Affected Components: + +* {{% ctx %}} Upgrade Scripts + +##### Execution Service is upgraded when the engine version is unchanged + +The Execution Service will now be upgraded when the engine version is unchanged. This is to ensure the upgrade works, including edge cases such as patches. + +Affected Components: + +* {{% ctx %}} Upgrade Scripts + +##### Handling of the Execution Services lifecycle events + +The Execution Services handle Service Fabric lifecycle events allowing flows to end gracefully within a defined period. +This includes a `Graceful Period timeout` and a `Cancel Period Timeout`, both which default to 5 minutes, and are configurable. + +Currently, there is no documentation available on how to do this. For further assistance, please raise a case in the [{{% ctx %}} Service Portal][]. + +Affected Components: + +* [{{% ctx %}} Innovation Core Application][] + * [{{% ctx %}} API Gateway Service][] + * [{{% ctx %}} Configuration Management Service][] +* [{{% ctx %}} Innovation Execution Application][] + * [{{% ctx %}} Execution Service][] +* [{{% ctx %}} Block Packages][Blocks] + +#### Documentation + +##### Process and Activity + +The [What is a Flow][] documentation has been updated to include information on the new concepts of [Processes][Process] and [Activities][Activity]. + +##### Decomposition of Output properties + +The [What is a Block Property][] documentation has been updated to include information on the new [Decomposition of Output properties][decomposition syntax] feature. + +##### Prevent deadlocks when using semaphores + +A new section has been added to the documentation explaining how to [prevent deadlocks][] when using semaphores. + +##### Screenshots updated + +Screenshots within the documentation has been updated to reflect the new branding, including [Blocks][] icons and various [{{% ctx %}} Gateway][] screenshots. + +##### Flow compatibility version introduced + +The [Flow compatibility version][] has been added to the release notes. + +##### General improvements to the documentation + +Various improvements have been made to the documentation to improve the overall quality and readability. + +### Bug Fixes + +#### Capability + +##### {{% ctx %}} Gateway encryptor not aligned with Service Fabric + +The Encryptor has been aligned between the {{% ctx %}} Gateway and Service Fabric. +This ensures that encrypted values created with the default key can still be decrypted if a custom private key has been set. + +Affected Components: + +* [{{% ctx %}} Gateway][Gateway] + +#### Upgrade + +##### Certificate update does not work after upgrade + +A bug has been fixed which prevented the update of certificates after an upgrade. + +Affected Components: + +* {{% ctx %}} Upgrade Scripts + +#### Documentation + +##### Missing Platform property in Log Event documentation + +The Platform property the the Log Event documentation was missing. This has been added to the documentation. + +### Breaking Changes + +The following features have introduced breaking changes in the 2024.9 release of the {{% ctx %}} Platform: + +#### Upgrade to .NET 8 + +The platform has been upgraded to [.NET 8][]. + +#### Reduction of total number of NServiceBus endpoints and RabbitMQ queues + +The following feature has changed internal endpoints and queues in the platform, which may cause issues if upgrading from 2024.7 to 2024.9 without upgrading all components at the same time. +The platform will need to be upgraded using the [Upgrade Instructions][]. + +#### Server-side validation added to {{% ctx %}} Gateway API + +The following feature has added validation to the [{{% ctx %}} Gateway][] API to prevent [Path Traversal][] attacks, which now returns an error if the path is invalid. + +### Known Limitations + +There are no known limitations added as part of the 2024.9 release of the {{% ctx %}} Platform. + +## Version Support + +### Operating Systems + +| OS Type | Supported Versions | +|---------|---------------------------------------------------| +| Windows | | +| Linux | Linux is not currently supported | + +### 7.X Compatibility + +| 7.X Version | Is compatible? | Notes | +|-------------|----------------|----------------------------------------------| +| 7.2 | Yes | | +| 7.1 | No | Need to upgrade 7.1 to 7.2 for compatibility | +| 7.0 | No | Need to upgrade 7.0 to 7.2 for compatibility | + +### Flow Compatibility + +| Release | Compatibility Version | +|---------|-----------------------| +| 2024.9 | 31.24311 | +| 2024.7 | 31.24311 | +| 2024.5 | 31.24311 | +| 2024.3 | 30 | + +## Install Instructions + +If you are installing a new 2024.9 platform or adding it to an existing 7.2 Installation see the guidance below; otherwise, if you are upgrading from an existing 2024.7 platform refer to the [Upgrade Instructions][]. + +Installing {{% ctx %}} Only: + +* [Multiple Server - With HA][Innovation Only - Multiple Server - With HA] +* [Single Server - Without HA][Innovation Only - Single Server - Without HA] + +Adding {{% ctx %}} to a 7.2 Installation: + +* [Multiple Server - With HA][Adding Innovation to a 7.2 Installation - Multiple Server - With HA] +* [Single Server - Without HA][Adding Innovation to a 7.2 Installation - Single Server - Without HA] + +## Upgrade Instructions + +If you are upgrading from an existing 2024.7 platform see the guidance below: + +Upgrading {{% ctx %}}: + +* [Multiple Server - With HA][Upgrade - Multiple Server - With HA] +* [Single Server - Without HA][Upgrade - Single Server - Without HA] + +## Upcoming Releases + +Releases are currently forecast to be made available on: + +| Release | Release Type | Forecast Release Date | +|---------|----------------|------------------------------------| +| 2024.9 | [Release][] | Week commencing 7th October 2024 | +| 2024.11 | [Fast Track][] | Week commencing 2nd December 2024 | +| 2025.1 | [Fast Track][] | Week commencing 10th February 2024 | + +[{{% ctx %}} Innovation Core Application]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.MainDoc" version="2024.9" >}} +[{{% ctx %}} API Gateway Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Authorisation Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.AuthorisationService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Concurrency Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConcurrencyManagementService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Configuration Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConfigurationManagementService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Data Storage Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Execution Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ExecutionManagementService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Licence Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.LicenceManagementService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Listeners Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ListenersService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Package Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.PackageManagementService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Provisioning Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ProvisioningService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Scheduling Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.SchedulingService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Triggers Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.TriggersService.MainDoc" version="2024.9" >}} +[{{% ctx %}} Innovation Execution Application]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.MainDoc" version="2024.9" >}} +[{{% ctx %}} Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" version="2024.9" >}} +[Interaction Portal]: {{< url path="Cortex.Guides.CortexInteractionPortal.MainDoc" version="2024.9" >}} + +[Process and Activity]: {{< ref "#process-and-activity" >}} +[Saving Output Properties to multiple variables]: {{< ref "#saving-output-properties-to-multiple-variables" >}} +[execution context variable]: {{< ref "#execution-context-variable" >}} +[Proxy for the {{% ctx %}} 7 Flow API]: {{< ref "#proxy-for-the-cortex-7-flow-api" >}} +[Observability]: {{< ref "#observability" >}} +[Logging added to blocks that communicate with external systems]: {{< ref "#logging-added-to-blocks-that-communicate-with-external-systems" >}} +[Scalability]: {{< ref "#scalability" >}} +[Reduction of total number of NServiceBus endpoints and RabbitMQ queues]: {{< ref "#reduction-of-total-number-of-nservicebus-endpoints-and-rabbitmq-queues" >}} +[Security]: {{< ref "#security" >}} +[Upgrade OpenSSL]: {{< ref "#upgrade-openssl" >}} +[Multi-domain certificates support]: {{< ref "#multi-domain-certificates-support" >}} +[New CortexManagementUser added to manage RabbitMQ queues]: {{< ref "#new-cortexmanagementuser-added-to-manage-rabbitmq-queues" >}} +[Server-side validation added to {{% ctx %}} Gateway API]: {{< ref "#server-side-validation-added-to-cortex-gateway-api" >}} +[Remove refresh token cookie on sign out]: {{< ref "#remove-refresh-token-cookie-on-sign-out" >}} +[Usability]: {{< ref "#usability" >}} +[Rename Flows Charm to Dev and change icon]: {{< ref "#rename-flows-charm-to-dev-and-change-icon" >}} +[Rename Settings Charm to Admin and change icon]: {{< ref "#rename-settings-charm-to-admin-and-change-icon" >}} +[Third-party Support]: {{< ref "#third-party-support" >}} +[Upgrade to .NET 8]: {{< ref "#upgrade-to-net-8" >}} +[Installation]: {{< ref "#installation" >}} +[Support installation when files are blocked by the operating system]: {{< ref "#support-installation-when-files-are-blocked-by-the-operating-system" >}} +[Upgrade]: {{< ref "#upgrade" >}} +[Support upgrade when files are blocked by the operating system]: {{< ref "#support-upgrade-when-files-are-blocked-by-the-operating-system" >}} +[Execution Service is upgraded when the engine version is unchanged]: {{< ref "#execution-service-is-upgraded-when-the-engine-version-is-unchanged" >}} +[Handling of the Execution Services lifecycle events]: {{< ref "#handling-of-the-execution-services-lifecycle-events" >}} +[Documentation]: {{< ref "#documentation" >}} +[Process and Activity Documentation]: {{< ref "#process-and-activity-1" >}} +[Decomposition of Output properties]: {{< ref "#decomposition-of-output-properties" >}} +[Prevent deadlocks when using semaphores]: {{< ref "#prevent-deadlocks-when-using-semaphores" >}} +[Screenshots updated]: {{< ref "#screenshots-updated" >}} +[Flow compatibility version introduced]: {{< ref "#flow-compatibility-version-introduced" >}} +[General improvements to the documentation]: {{< ref "#general-improvements-to-the-documentation" >}} + +[Flow compatibility version]: {{< ref "#flow-compatibility" >}} + +[Upgrade Instructions]: {{< ref "#upgrade-instructions" >}} + +[{{% ctx %}} Gateway]: {{< url path="Cortex.Guides.Gateway.MainDoc" version="2024.9" >}} +[Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" version="2024.9" >}} +[What is a Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" version="2024.9" >}} +[Process]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.Process" version="2024.9" >}} +[Activity]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.Activity" version="2024.9" >}} +[What is a Block Property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" version="2024.9" >}} + +[prevent deadlocks]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.PreventingDeadlocks" version="2024.9" >}} + +[Execute Data Command]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.MainDoc" version="2024.9" >}} +[DataCommand]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" version="2024.9" >}} + +[Execute HTTP Request]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest.MainDoc" version="2024.9" >}} +[HttpRequest]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest.HttpRequestProperty" version="2024.9" >}} +[HttpResponse]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest.HttpResponseProperty" version="2024.9" >}} + +[Execute Soap Request]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequest.MainDoc" version="2024.9" >}} +[SoapRequest]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequest.SoapRequestProperty" version="2024.9" >}} +[SoapResponse]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequest.SoapResponseProperty" version="2024.9" >}} + +[Execute Powershell Script]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.MainDoc" version="2024.9" >}} +[Script]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.ScriptProperty" version="2024.9" >}} +[Parameters]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.ParametersProperty" version="2024.9" >}} +[Outputs]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.OutputsProperty" version="2024.9" >}} +[Records]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.RecordsProperty" version="2024.9" >}} + +[Execute SSH Command]: {{< url path="Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock.MainDoc" version="2024.9" >}} +[Command]: {{< url path="Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock.CommandProperty" version="2024.9" >}} +[Response]: {{< url path="Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock.Response" version="2024.9" >}} +[SSH Logs]: {{< url path="Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock.SshLogsProperty" version="2024.9" >}} + +[Gateway]: {{< url path="Cortex.Guides.Gateway.MainDoc" version="2024.9" >}} +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" version="2024.9" >}} +[decomposition syntax]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DecomposingOutputProperties" version="2024.9" >}} + +[.NET 8]: {{< url path="Cortex.Reference.Glossary.A-E.DotNet" >}} +[API]: {{< url path="Cortex.Reference.Glossary.A-E.API" >}} +[Service Fabric]: {{< url path="Cortex.Reference.Glossary.P-T.ServiceFabric" >}} +[built-in _executionContext variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.ExecutionContext" version="2024.9" >}} + +[Innovation Only - Single Server - Without HA]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.MainDoc" version="2024.9" >}} +[Innovation Only - Multiple Server - With HA]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.MainDoc" version="2024.9" >}} + +[Adding Innovation to a 7.2 Installation - Single Server - Without HA]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.MainDoc" version="2024.9" >}} +[Adding Innovation to a 7.2 Installation - Multiple Server - With HA]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.MainDoc" version="2024.9" >}} + +[Upgrade - Single Server - Without HA]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.MainDoc" version="2024.9" >}} +[Upgrade - Multiple Server - With HA]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.MainDoc" version="2024.9" >}} +[Breaking - Reduction of total number of NServiceBus endpoints and RabbitMQ queues]: {{< ref "#reduction-of-total-number-of-nservicebus-endpoints-and-rabbitmq-queues-1" >}} +[Breaking - Upgrade to .NET 8]: {{< ref "#upgrade-to-net-8-1" >}} +[Breaking - Server-side validation added to {{% ctx %}} Gateway API]: {{< ref "#server-side-validation-added-to-cortex-gateway-api-1" >}} + +[{{% ctx %}} Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" version="2024.9" >}} + +[{{% ctx %}} Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" version="2024.9" >}} + +[Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" version="2024.9" >}} + +[Fast Track]: {{< url path="Cortex.Reference.Glossary.F-J.FastTrack" version="2024.9" >}} +[Release]: {{< url path="Cortex.Reference.Glossary.P-T.Release" version="2024.9" >}} + +[2024.7]: {{< url path="Cortex.Blogs.Releases.2024.7.MainDoc" version="2024.9" >}} + +[Path Traversal]: {{< url path="Owasp.PathTraversal.MainDoc" version="2024.9" >}} diff --git a/content/en/docs/2024.7/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md b/content/en/docs/2024.7/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md index c3c3fc918..ff7f1c0d2 100644 --- a/content/en/docs/2024.7/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md +++ b/content/en/docs/2024.7/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md @@ -333,6 +333,7 @@ Innovation has a [gobetween][] load balancer included that isn't highly availabl [alternative load balancer]: {{< ref "#alternative-load-balancer-requirements" >}} [Anycast]: {{< url path="Anycast.MainDoc" >}} [Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.Architecture" >}} +[Create Full DB Backup]: {{< url path="MSDocs.SqlServer.CreateFullDbBackup" >}} [C++ Redistributable]: {{< url path="MSDownload.CPlusPlusRedistributable.2013" >}} [CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} [gobetween]: {{< url path="GoBetween.MainDoc" >}} diff --git a/content/en/docs/2024.9/FAQs/_index.md b/content/en/docs/2024.9/FAQs/_index.md new file mode 100644 index 000000000..654613e9b --- /dev/null +++ b/content/en/docs/2024.9/FAQs/_index.md @@ -0,0 +1,8 @@ +--- +title: "FAQs" +linkTitle: "FAQs" +description: "Answers to our most frequently asked questions." +weight: 10000 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/_index.md b/content/en/docs/2024.9/Guides/_index.md new file mode 100644 index 000000000..e9ff0c934 --- /dev/null +++ b/content/en/docs/2024.9/Guides/_index.md @@ -0,0 +1,6 @@ +--- +title: "Guides" +linkTitle: "Guides" +description: "This section includes all guides for the {{% ctx %}} Innovation platform." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/_index.md b/content/en/docs/2024.9/Guides/cortex-gateway/_index.md new file mode 100644 index 000000000..30d09957b --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/_index.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Gateway" +linkTitle: "CORTEX Gateway" +description: "The centralised web-based portal for accessing all user applications and tooling in the {{% ctx %}} Innovation platform." +weight: 1 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/help/_index.md b/content/en/docs/2024.9/Guides/cortex-gateway/help/_index.md new file mode 100644 index 000000000..dae7d1fc2 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/help/_index.md @@ -0,0 +1,7 @@ +--- +title: "Help" +linkTitle: "Help" +description: "System level help" +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/help/cortex-release-notes.md b/content/en/docs/2024.9/Guides/cortex-gateway/help/cortex-release-notes.md new file mode 100644 index 000000000..e60258650 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/help/cortex-release-notes.md @@ -0,0 +1,7 @@ +--- +title: "Release Notes" +linkTitle: "Release Notes" +description: "Release notes for all currently available {{% ctx %}} Versions." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/_index.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/_index.md new file mode 100644 index 000000000..4303ed2bb --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/_index.md @@ -0,0 +1,7 @@ +--- +title: "CORTEX Gateway Management" +linkTitle: "CORTEX Gateway Management" +description: "{{% ctx %}} Gateway and Studio Management tools and settings" +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-authorisation.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-authorisation.md new file mode 100644 index 000000000..e4e6647d0 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-authorisation.md @@ -0,0 +1,7 @@ +--- +title: "LDAP Authorisation" +linkTitle: "LDAP Authorisation" +description: "Configure RBAC by assining roles to security groups." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-connection.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-connection.md new file mode 100644 index 000000000..9d4f4c87f --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/ldap-connection.md @@ -0,0 +1,7 @@ +--- +title: "LDAP Connection" +linkTitle: "LDAP Connection" +description: "Connect to an Active Directory using LDAP." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/license-consumption.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/license-consumption.md new file mode 100644 index 000000000..fdb2d879d --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/license-consumption.md @@ -0,0 +1,7 @@ +--- +title: "License Consumption" +linkTitle: "License Consumption" +description: "Review current license consumption of flows in master." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/packages.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/packages.md new file mode 100644 index 000000000..c42f0f395 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/packages.md @@ -0,0 +1,7 @@ +--- +title: "Packages" +linkTitle: "Packages" +description: "Create and Manage {{% ctx %}} Innovation Packages" +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-authorisation.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-authorisation.md new file mode 100644 index 000000000..58ecac5b6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-authorisation.md @@ -0,0 +1,7 @@ +--- +title: "Studio Authorisation" +linkTitle: "Studio Authorisation" +description: "Assign access rights to flows based on security groups." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-export.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-export.md new file mode 100644 index 000000000..21de622a6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-export.md @@ -0,0 +1,7 @@ +--- +title: "Studio Export" +linkTitle: "Studio Export" +description: "Create {{% ctx %}} Studio Packages by exporting flows." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-hierarchy.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-hierarchy.md new file mode 100644 index 000000000..27a09993e --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-hierarchy.md @@ -0,0 +1,7 @@ +--- +title: "Studio Hierarchy" +linkTitle: "Studio Hierarchy" +description: "Manage the location of flows in the Flow Hierarchy." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-import.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-import.md new file mode 100644 index 000000000..28a685526 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/studio-import.md @@ -0,0 +1,7 @@ +--- +title: "Studio Import" +linkTitle: "Studio Import" +description: "Import {{% ctx %}} Studio Packages." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/settings/version-control.md b/content/en/docs/2024.9/Guides/cortex-gateway/settings/version-control.md new file mode 100644 index 000000000..7033dc287 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/settings/version-control.md @@ -0,0 +1,7 @@ +--- +title: "Version Control" +linkTitle: "Version Control" +description: "High level view of flows out of sync with master. Allow for mass Commit or Get Master" +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-gateway/welcome-page/_index.md b/content/en/docs/2024.9/Guides/cortex-gateway/welcome-page/_index.md new file mode 100644 index 000000000..04b16f12a --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-gateway/welcome-page/_index.md @@ -0,0 +1,13 @@ +--- +title: "Welcome Page" +linkTitle: "Welcome Page" +description: "Welcome Page" +--- + +{{< workinprogress >}} + +## Summary + +## Recently Edited Flows + +TODO: Summary, Screenshots diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/_index.md new file mode 100644 index 000000000..47faeb366 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/_index.md @@ -0,0 +1,6 @@ +--- +title: "CORTEX Innovation" +linkTitle: "CORTEX Innovation" +description: "The {{% ctx %}} Innovation platform." +weight: 300 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/_index.md new file mode 100644 index 000000000..87cdd11cd --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Core Application" +linkTitle: "Core Application" +description: "The Core Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/_index.md new file mode 100644 index 000000000..3bb8a5855 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "The Core Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/api-gateway-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/api-gateway-service/_index.md new file mode 100644 index 000000000..31c122c46 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/api-gateway-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "API Gateway Service" +linkTitle: "API Gateway Service" +description: "The API Gateway Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/authorisation-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/authorisation-service/_index.md new file mode 100644 index 000000000..9ff8c5979 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/authorisation-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Authorisation Service" +linkTitle: "Authorisation Service" +description: "The Authorisation Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/concurrency-management-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/concurrency-management-service/_index.md new file mode 100644 index 000000000..8974784b2 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/concurrency-management-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Concurrency Management Service" +linkTitle: "Concurrency Management Service" +description: "The Concurrency Management Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/configuration-management-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/configuration-management-service/_index.md new file mode 100644 index 000000000..0e25b5739 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/configuration-management-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Configuration Management Service" +linkTitle: "Configuration Management Service" +description: "The Configuration Management Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/data-storage-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/data-storage-service/_index.md new file mode 100644 index 000000000..61d5fb9d1 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/data-storage-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Data Storage Service" +linkTitle: "Data Storage Service" +description: "The Data Storage Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/execution-management-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/execution-management-service/_index.md new file mode 100644 index 000000000..4b49b1866 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/execution-management-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Execution Management Service" +linkTitle: "Execution Management Service" +description: "The Execution Management Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/licence-management-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/licence-management-service/_index.md new file mode 100644 index 000000000..ad3a309fd --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/licence-management-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Licence Management Service" +linkTitle: "Licence Management Service" +description: "The Licence Management Service." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/listeners-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/listeners-service/_index.md new file mode 100644 index 000000000..3cc2cd206 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/listeners-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Listeners Service" +linkTitle: "Listeners Service" +description: "The Listeners Service." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/package-management-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/package-management-service/_index.md new file mode 100644 index 000000000..8e451b3a7 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/package-management-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Package Management Service" +linkTitle: "Package Management Service" +description: "The Package Management Service." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/provisioning-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/provisioning-service/_index.md new file mode 100644 index 000000000..165229e50 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/provisioning-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Provisioning Service" +linkTitle: "Provisioning Service" +description: "The Provisioning Service." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/scheduling-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/scheduling-service/_index.md new file mode 100644 index 000000000..4a06f4fdf --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/scheduling-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Scheduling Service" +linkTitle: "Scheduling Service" +description: "The Scheduling Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/triggers-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/triggers-service/_index.md new file mode 100644 index 000000000..415b9aa71 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/core-application/services/triggers-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Triggers Service" +linkTitle: "Triggers Service" +description: "The Triggers Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/_index.md new file mode 100644 index 000000000..3ec60b6f4 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Execution Application" +linkTitle: "Execution Application" +description: "The Execution Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/_index.md new file mode 100644 index 000000000..33f2fe7b6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "The Execution Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/execution-service/_index.md b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/execution-service/_index.md new file mode 100644 index 000000000..3c8bea4c3 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-innovation/execution-application/services/execution-service/_index.md @@ -0,0 +1,7 @@ +--- +title: "Execution Service" +linkTitle: "Execution Service" +description: "The Execution Service." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/cortex-interaction-portal/_index.md b/content/en/docs/2024.9/Guides/cortex-interaction-portal/_index.md new file mode 100644 index 000000000..797357f30 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-interaction-portal/_index.md @@ -0,0 +1,10 @@ +--- +title: "CORTEX Interaction Portal" +linkTitle: "CORTEX Interaction Portal" +description: "A web application that provides Human-in-the-Loop capabilities to the {{% ctx %}} Innovation platform." +weight: 400 +--- + +* {{< filelink src="/pdf/Cortex Interaction Portal User Guide.pdf" name="CORTEX Interaction Portal User Guide" >}} +* {{< filelink src="/pdf/Cortex Interaction Portal Developer Guide.pdf" name="CORTEX Interaction Portal Developer Guide" >}} +* {{< filelink src="/pdf/Cortex Interaction Portal Merging Guide.pdf" name="CORTEX Interaction Portal Merging Guide" >}} diff --git a/content/en/docs/2024.9/Guides/cortex-studio/_index.md b/content/en/docs/2024.9/Guides/cortex-studio/_index.md new file mode 100644 index 000000000..d54973ba6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/_index.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Studio" +linkTitle: "CORTEX Studio" +description: "The web-based, low-code, integrated development environment (IDE) for creating, editing, debugging, testing and managing flows that define the logic and actions required to capture and automate simple user tasks through to complex business or IT processes." +weight: 100 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-studio/debugging.md b/content/en/docs/2024.9/Guides/cortex-studio/debugging.md new file mode 100644 index 000000000..3e3ed9f9e --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/debugging.md @@ -0,0 +1,20 @@ +--- +title: "Debugging" +linkTitle: "Debugging" +description: "" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Property Viewer + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/east-panel.md b/content/en/docs/2024.9/Guides/cortex-studio/east-panel.md new file mode 100644 index 000000000..94a52f91e --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/east-panel.md @@ -0,0 +1,40 @@ +--- +title: "CORTEX Studio - East Panel (TBC)" +linkTitle: "CORTEX Studio - East Panel (TBC)" +description: "Eastern panel for Property Editor, Execution Viewer and Exceptions" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Property Editor + +### Add Variables button + +### Show/Hide Advanced Properties button + +### Help button + +## Execution Viewer + +### Variables Viewer + +#### Variable Details Viewer + +##### Load Value Button + +### Exceptions Viewer + +## Settings Editor + +### Inputs Property + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/expression-editor.md b/content/en/docs/2024.9/Guides/cortex-studio/expression-editor.md new file mode 100644 index 000000000..c2016f173 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/expression-editor.md @@ -0,0 +1,34 @@ +--- +title: "CORTEX Studio - Expression Editor" +linkTitle: "CORTEX Studio - Expression Editor" +description: "A guide on how to use the Expression Editor" +weight: 0 +--- + +{{< workinprogress >}} + +## Summary + +TODO: What is used for, etc. + +## Snippets + +TODO: How to Access, Whats Available, etc + +## Tools + +TODO: Full Screen, Find and Replace, Command Menu, Replace All (Ctrl F2), etc + +## Example Expressions + +TODO: Variable, Object Construct (Complex/Collection), String Concatenation/Interpolation, Arithmetics, etc + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts + +TODO diff --git a/content/en/docs/2024.9/Guides/cortex-studio/literal-editor.md b/content/en/docs/2024.9/Guides/cortex-studio/literal-editor.md new file mode 100644 index 000000000..5b76f0261 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/literal-editor.md @@ -0,0 +1,26 @@ +--- +title: "CORTEX Studio - Literal Editor" +linkTitle: "CORTEX Studio - Literal Editor" +description: "A guide on how to use the Literal Editor" +weight: 0 +--- + +{{< workinprogress >}} + +## Summary + +TODO: What is used for, etc. + +## Selecting a Literal Type + +TODO: Searching/Filtering + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts + +TODO diff --git a/content/en/docs/2024.9/Guides/cortex-studio/main-display-area.md b/content/en/docs/2024.9/Guides/cortex-studio/main-display-area.md new file mode 100644 index 000000000..2547a75c9 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/main-display-area.md @@ -0,0 +1,72 @@ +--- +title: "CORTEX Studio - Main Display Area" +linkTitle: "CORTEX Studio - Main Display Area" +description: "The Main Display Area for developing and managing a flow" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Main Toolbar + +### Undo + +TODO: + +- What happens when an undo action is taken +- What can be undone +- Keyboard Shortcuts? + +### Redo + +TODO: + +- What happens when an redo action is taken +- What can be redone +- Keyboard Shortcuts? + +### Start an execution + +TODO: + +- Should this be called 'starting an execution' or 'debugging an execution' +- Start execution via API or Studio + - describe the steps of starting from API (API call is made to Gateway, Authentication and Authorisation is performed, etc) + - describe the steps of starting from Studio (User clicks button, call is made to Gateway, Authentication and Authorisation is performed, etc) +- Image of button and token after button was pressed +- Executions are private and only displayed to the user that requested them (Check this is true, look at the APIs). +- link debugging in this page to glossary +- link 'what is an execution.md' debugging/production to glossary +- Providing input variables (API or Studio) + - literals and expression +- Retrieving Output variables (API or Studio) + +#### Break On Exception + +TODO + +### Edit and Continue an Execution + +## Workspaces + +### Blocks + +#### Breakpoints + +### Executions + +Executions are represented by tokens on a workspace. + +#### Set Next Block to Execute + +## Workspace Toolbar + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/navigation.md b/content/en/docs/2024.9/Guides/cortex-studio/navigation.md new file mode 100644 index 000000000..25ffb0804 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/navigation.md @@ -0,0 +1,24 @@ +--- +title: "CORTEX Studio - Navigation" +linkTitle: "CORTEX Studio - Navigation" +description: "How to navigate between and in flows" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Breadcrumb trail + +## Quick Navigation + +## Swimlane Management + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/package-management.md b/content/en/docs/2024.9/Guides/cortex-studio/package-management.md new file mode 100644 index 000000000..31bea9f7b --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/package-management.md @@ -0,0 +1,20 @@ +--- +title: "CORTEX Studio - Package Management (TBC)" +linkTitle: "CORTEX Studio - Package Management (TBC)" +description: "Package Management" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Automatic Selection of Dependent Flows + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/palettes.md b/content/en/docs/2024.9/Guides/cortex-studio/palettes.md new file mode 100644 index 000000000..38e9742f5 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/palettes.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Studio - Palettes" +linkTitle: "CORTEX Studio - Palettes" +description: "Block palette information" +weight: 1 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Guides/cortex-studio/south-panel.md b/content/en/docs/2024.9/Guides/cortex-studio/south-panel.md new file mode 100644 index 000000000..0e8f75286 --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/south-panel.md @@ -0,0 +1,68 @@ +--- +title: "CORTEX Studio - South Panel (TBC)" +linkTitle: "CORTEX Studio - South Panel (TBC)" +description: "Southern panel for Executions, Messages, and Variables" +weight: 1 +--- + +{{< workinprogress >}} + +## Summary + +## Executions Grid + +### Pausing an Execution + +### Stepping an Execution + +### Continuing an Execution + +### Stopping an Execution + +## Variables Grid + +TODO: Add Screenshot of Grid + +### Creating Variables + +TODO: Screenshots, How to create + +### Viewing Variables + +TODO: Screenshots, Searching/Filtering + +### Renaming Variables + +TODO: Screenshots, Searching/Filtering + +### Modifying Variables + +TODO: Screenshots, How to modify + +#### Changing a Variable's Scope + +TODO: Screenshots, how to modify scope + +1. Find the variable in the [Variable Grid][] +2. Double-click the **Scope** to load a dropdown menu +3. Select the desired workspace + +If the variable does not appear in the grid, the most likely reason is the variable is not in scope of the workspace currently in focus. To resolve this, either select the appropriate workspace, or change the **Scope** filter on the [Variable Grid][] to **All**. + +### Deleting Variables + +TODO: Screenshots, How to delete + +### Validating Variables + +TODO: Screenshots + +## Messages Grid + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts diff --git a/content/en/docs/2024.9/Guides/cortex-studio/variable-editor.md b/content/en/docs/2024.9/Guides/cortex-studio/variable-editor.md new file mode 100644 index 000000000..79b9d2faa --- /dev/null +++ b/content/en/docs/2024.9/Guides/cortex-studio/variable-editor.md @@ -0,0 +1,31 @@ +--- +title: "CORTEX Studio - Variable Editor" +linkTitle: "CORTEX Studio - Variable Editor" +description: "A guide on how to use the Variable Editor" +weight: 0 +--- + +{{< workinprogress >}} + +## Summary + +TODO: What is used for, etc. + +## Selecting Variables + +TODO: Searching/Filtering +TODO: Complex/Collection variable referencing + +## Creating Variables + +TODO: Create variable from property, create all undefined variables + +## Remarks + +### Known Limitations + +## See Also + +### Related Concepts + +TODO diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/_index.md new file mode 100644 index 000000000..719b7315d --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/_index.md @@ -0,0 +1,6 @@ +--- +title: "2024.1 to 2024.3" +linkTitle: "2024.1 to 2024.3" +description: "Instructions to upgrade {{% ctx %}} 2024.1 to 2024.3" +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..10ed76d03 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Multiple Server - With HA" +linkTitle: "Multiple Server - With HA" +description: "Upgrade instructions for multiple on-premise servers with high availability (HA)." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..5a8a0e4d3 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Servers and Load Balancer Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.3/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/multi-server/test-executing-production-flows.md" >}} + +[Application Servers and Load Balancer Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..7aa892b26 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md @@ -0,0 +1,65 @@ +--- +title: "Upgrade Application Servers and Load Balancer" +linkTitle: "Upgrade Application Servers and Load Balancer" +description: "Information about upgrading the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Servers and Load Balancer Server from 2024.1 to 2024.3. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used to perform the upgrade from, and copy the following artefacts to a folder on it: + * Cortex Innovation 2024.3 - App Server Install Scripts.zip + * Cortex Innovation 2024.3 - App Services.zip + * Cortex Innovation 2024.3 - Block Packages.zip + +1. Extract the `Cortex Innovation 2024.3 - App Server Install Scripts.zip` file to a folder with the same name. + +## Configure Upgrade Script + +1. In the `Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Configure the script, changing the parameters according to the details given below: + + ```powershell + .\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.3 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.3 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1, 192.168.1.2, 192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + ``` + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server being used for the upgrade. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server being used for the upgrade. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server being used for the upgrade.| + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. If the built-in load balancer is not being used, this should be removed.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. + +## Run Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-application-server/multi-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/multi-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/_index.md new file mode 100644 index 000000000..956ddc1d6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Upgrade the Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server." +weight: 40 +--- + +This guide describes how to upgrade the Web Application Server. Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.1 version of Gateway and its prerequisites have already been installed. + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md new file mode 100644 index 000000000..97990aab4 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md @@ -0,0 +1,30 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Upgrade of the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.1 version of Gateway and its prerequisites have already been installed. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation 2024.3 - App Services.zip + * Cortex Innovation 2024.3 - App Server Install Scripts.zip + * Cortex Innovation 2024.3 - Block Packages.zip + * Cortex Innovation 2024.3 - Gateway.zip + * Cortex Innovation 2024.3 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.3 - App Server Install Scripts.zip` file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.3 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Next Steps? + +1. [Upgrade Flow Debugger][] + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Upgrade Flow Debugger]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeDebugger" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md new file mode 100644 index 000000000..e896f3e3a --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md @@ -0,0 +1,32 @@ +--- +title: "Upgrade Flow Debugger" +linkTitle: "Upgrade Flow Debugger" +description: "Information about upgrading the Flow Debugger." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Flow Debugger on the Web Application Server from 2024.1 to 2024.3. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-application-server/single-server/run-upgrade-script.md">}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade Gateway][] + +[Upgrade Gateway]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeGateway" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md new file mode 100644 index 000000000..e13598a03 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md @@ -0,0 +1,29 @@ +--- +title: "Upgrade Gateway" +linkTitle: "Upgrade Gateway" +description: "Information about upgrading {{% ctx %}} Gateway from 2024.1 to 2024.3." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.1 to 2024.3. Please ensure that the [Flow Debugger upgrade][] has been completed before starting this upgrade. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-web-application-server/run-gateway-script.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Flow Debugger upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.UpgradeDebugger" >}} +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/_index.md new file mode 100644 index 000000000..a43e88369 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Upgrade instructions for a single on-premise server without high availability (HA)." +weight: 500 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..05aa5aa36 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Server Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.3/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/single-server/test-executing-production-flows.md" >}} + +[Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.SingleServerWithoutHA.UpgradeApplicationServer" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-application-server.md new file mode 100644 index 000000000..4f698ff4c --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-application-server.md @@ -0,0 +1,37 @@ +--- +title: "Upgrade Application Server" +linkTitle: "Upgrade Application Server" +description: "Information about upgrading the Application Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Server components on the server from 2024.1 to 2024.3. + +## Make Installation Artefacts Available + +{{< section "/upgrade/2024.3/upgrade-application-server/single-server/make-installation-artefacts-available.md" >}} + +## Configure Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-application-server/single-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} + diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-web-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-web-application-server.md new file mode 100644 index 000000000..7757a353f --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.1-to-2024.3/single-server-without-ha/upgrade-web-application-server.md @@ -0,0 +1,38 @@ +--- +title: "Upgrade Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server from 2024.1 to 2024.3." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.1 to 2024.3. Please ensure that the [Upgrade Application Server][] has been completed before starting this upgrade. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the server: + + * Cortex Innovation 2024.5 - Gateway.zip + * Cortex Innovation 2024.5 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.5 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.3/upgrade-web-application-server/run-gateway-script.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.SingleServerWithoutHA.TryItOut" >}} +[Upgrade Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.1to2024.3.SingleServerWithoutHA.UpgradeApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/_index.md new file mode 100644 index 000000000..d180e4d11 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/_index.md @@ -0,0 +1,6 @@ +--- +title: "2024.3 to 2024.5" +linkTitle: "2024.3 to 2024.5" +description: "Instructions to upgrade {{% ctx %}} 2024.3 to 2024.5" +weight: 999 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..10ed76d03 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Multiple Server - With HA" +linkTitle: "Multiple Server - With HA" +description: "Upgrade instructions for multiple on-premise servers with high availability (HA)." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..df5e453b7 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Servers and Load Balancer Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.5/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/multi-server/test-executing-production-flows.md" >}} + +[Application Servers and Load Balancer Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..2b7972aa8 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md @@ -0,0 +1,65 @@ +--- +title: "Upgrade Application Servers and Load Balancer" +linkTitle: "Upgrade Application Servers and Load Balancer" +description: "Information about upgrading the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Servers and Load Balancer Server from 2024.3 to 2024.5. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used to perform the upgrade from, and copy the following artefacts to a folder on it: + * Cortex Innovation 2024.5 - App Server Install Scripts.zip + * Cortex Innovation 2024.5 - App Services.zip + * Cortex Innovation 2024.5 - Block Packages.zip + +1. Extract the `Cortex Innovation 2024.5 - App Server Install Scripts.zip` file to a folder with the same name. + +## Configure Upgrade Script + +1. In the `Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Configure the script, changing the parameters according to the details given below: + + ```powershell + .\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.5 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.5 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1, 192.168.1.2, 192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + ``` + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server being used for the upgrade. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server being used for the upgrade. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server being used for the upgrade.| + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. If the built-in load balancer is not being used, this should be removed.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. + +## Run Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-application-server/multi-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/multi-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/_index.md new file mode 100644 index 000000000..d935713ea --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Upgrade the Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server." +weight: 40 +--- + +This guide describes how to upgrade the Web Application Server. Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.3 version of Gateway and its prerequisites have already been installed. + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md new file mode 100644 index 000000000..d749f6f71 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md @@ -0,0 +1,30 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Upgrade of the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.3 version of Gateway and its prerequisites have already been installed. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation 2024.5 - App Services.zip + * Cortex Innovation 2024.5 - App Server Install Scripts.zip + * Cortex Innovation 2024.5 - Block Packages.zip + * Cortex Innovation 2024.5 - Gateway.zip + * Cortex Innovation 2024.5 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.5 - App Server Install Scripts.zip` file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.5 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Next Steps? + +1. [Upgrade Flow Debugger][] + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Upgrade Flow Debugger]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeDebugger" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md new file mode 100644 index 000000000..cdf7307cc --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md @@ -0,0 +1,32 @@ +--- +title: "Upgrade Flow Debugger" +linkTitle: "Upgrade Flow Debugger" +description: "Information about upgrading the Flow Debugger." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Flow Debugger on the Web Application Server from 2024.3 to 2024.5. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-application-server/single-server/run-upgrade-script.md">}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade Gateway][] + +[Upgrade Gateway]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeGateway" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md new file mode 100644 index 000000000..92748ba31 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md @@ -0,0 +1,29 @@ +--- +title: "Upgrade Gateway" +linkTitle: "Upgrade Gateway" +description: "Information about upgrading {{% ctx %}} Gateway from 2024.3 to 2024.5." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.3 to 2024.5. Please ensure that the [Flow Debugger upgrade][] has been completed before starting this upgrade. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-web-application-server/run-gateway-script.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Flow Debugger upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.UpgradeDebugger" >}} +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/_index.md new file mode 100644 index 000000000..a43e88369 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Upgrade instructions for a single on-premise server without high availability (HA)." +weight: 500 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..e6deaefdb --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Server Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.5/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/single-server/test-executing-production-flows.md" >}} + +[Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.SingleServerWithoutHA.UpgradeApplicationServer" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-application-server.md new file mode 100644 index 000000000..a378b3b86 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-application-server.md @@ -0,0 +1,37 @@ +--- +title: "Upgrade Application Server" +linkTitle: "Upgrade Application Server" +description: "Information about upgrading the Application Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Server components on the server from 2024.3 to 2024.5. + +## Make Installation Artefacts Available + +{{< section "/upgrade/2024.5/upgrade-application-server/single-server/make-installation-artefacts-available.md" >}} + +## Configure Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-application-server/single-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} + diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-web-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-web-application-server.md new file mode 100644 index 000000000..2011d979e --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.3-to-2024.5/single-server-without-ha/upgrade-web-application-server.md @@ -0,0 +1,38 @@ +--- +title: "Upgrade Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server from 2024.3 to 2024.5." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.3 to 2024.5. Please ensure that the [Upgrade Application Server][] has been completed before starting this upgrade. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the server: + + * Cortex Innovation 2024.5 - Gateway.zip + * Cortex Innovation 2024.5 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.5 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.5/upgrade-web-application-server/run-gateway-script.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.SingleServerWithoutHA.TryItOut" >}} +[Upgrade Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.3to2024.5.SingleServerWithoutHA.UpgradeApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/_index.md new file mode 100644 index 000000000..b8251f69d --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/_index.md @@ -0,0 +1,6 @@ +--- +title: "2024.5 to 2024.7" +linkTitle: "2024.5 to 2024.7" +description: "Instructions to upgrade {{% ctx %}} 2024.5 to 2024.7" +weight: 998 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..10ed76d03 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Multiple Server - With HA" +linkTitle: "Multiple Server - With HA" +description: "Upgrade instructions for multiple on-premise servers with high availability (HA)." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..f2dd5df57 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Servers and Load Balancer Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.7/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/multi-server/test-executing-production-flows.md" >}} + +[Application Servers and Load Balancer Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..61d52ecd6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md @@ -0,0 +1,79 @@ +--- +title: "Upgrade Application Servers and Load Balancer" +linkTitle: "Upgrade Application Servers and Load Balancer" +description: "Information about upgrading the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Servers and Load Balancer Server from 2024.5 to 2024.7. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used to perform the upgrade from, and copy the following artefacts to a folder on it: + * Cortex Innovation 2024.7 - App Server Install Scripts.zip + * Cortex Innovation 2024.7 - App Services.zip + * Cortex Innovation 2024.7 - Block Packages.zip + +1. Extract the `Cortex Innovation 2024.7 - App Server Install Scripts.zip` file to a folder with the same name. + +## Configure Upgrade Script + +1. In the `Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.ApplicationConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or the values should be changed then use the `Use New Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.7 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.7 - Block Packages.zip" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.7 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.7 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1, 192.168.1.2, 192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server being used for the upgrade. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server being used for the upgrade. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server being used for the upgrade.| + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. If the built-in load balancer is not being used, this should be removed.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. + +## Run Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-application-server/multi-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/multi-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/_index.md new file mode 100644 index 000000000..82bc958cb --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Upgrade the Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server." +weight: 40 +--- + +This guide describes how to upgrade the Web Application Server. Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.5 version of Gateway and its prerequisites have already been installed. + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md new file mode 100644 index 000000000..5645bd0eb --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md @@ -0,0 +1,32 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Upgrade of the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.5 version of Gateway and its prerequisites have already been installed. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation 2024.7 - App Services.zip + * Cortex Innovation 2024.7 - App Server Install Scripts.zip + * Cortex Innovation 2024.7 - Block Packages.zip + * Cortex Innovation 2024.7 - Gateway.zip + * Cortex Innovation 2024.7 - Flows Upgrader.zip + * Cortex Innovation 2024.7 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.7 - App Server Install Scripts.zip` file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.7 - Flows Upgrader.zip` zip file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.7 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Next Steps? + +1. [Upgrade Flow Debugger][] + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Upgrade Flow Debugger]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeDebugger" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md new file mode 100644 index 000000000..a0bd3fc93 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md @@ -0,0 +1,32 @@ +--- +title: "Upgrade Flow Debugger" +linkTitle: "Upgrade Flow Debugger" +description: "Information about upgrading the Flow Debugger." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Flow Debugger on the Web Application Server from 2024.5 to 2024.7. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-application-server/single-server/run-upgrade-script.md">}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade Gateway][] + +[Upgrade Gateway]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeGateway" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md new file mode 100644 index 000000000..813475bf1 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md @@ -0,0 +1,37 @@ +--- +title: "Upgrade Gateway" +linkTitle: "Upgrade Gateway" +description: "Information about upgrading {{% ctx %}} Gateway from 2024.5 to 2024.7." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.5 to 2024.7. Please ensure that the [Flow Debugger upgrade][] has been completed before starting this upgrade. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-web-application-server/run-gateway-script.md" >}} + +## Upgrade Flows + +{{< section "/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md" >}} + +{{% alert title="Note" %}} +If the {{% ctx %}} Interaction Portal is used in your environment, you must also upgrade those flows. +{{% /alert %}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Flow Debugger upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.UpgradeDebugger" >}} +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/_index.md new file mode 100644 index 000000000..a43e88369 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Upgrade instructions for a single on-premise server without high availability (HA)." +weight: 500 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..4577a2be6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Server Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.7/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/single-server/test-executing-production-flows.md" >}} + +[Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.SingleServerWithoutHA.UpgradeApplicationServer" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-application-server.md new file mode 100644 index 000000000..6f25888bf --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-application-server.md @@ -0,0 +1,37 @@ +--- +title: "Upgrade Application Server" +linkTitle: "Upgrade Application Server" +description: "Information about upgrading the Application Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Server components on the server from 2024.5 to 2024.7. + +## Make Installation Artefacts Available + +{{< section "/upgrade/2024.7/upgrade-application-server/single-server/make-installation-artefacts-available.md" >}} + +## Configure Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-application-server/single-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} + diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-web-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-web-application-server.md new file mode 100644 index 000000000..947a007c9 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-web-application-server.md @@ -0,0 +1,48 @@ +--- +title: "Upgrade Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server from 2024.5 to 2024.7." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.5 to 2024.7. Please ensure that the [Upgrade Application Server][] has been completed before starting this upgrade. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the server: + + * Cortex Innovation 2024.7 - Gateway.zip + * Cortex Innovation 2024.7 - Flows Upgrader.zip + * Cortex Innovation 2024.7 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.7 - Flows Upgrader.zip` zip file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.7 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.7/upgrade-web-application-server/run-gateway-script.md" >}} + +## Upgrade Flows + +{{< section "/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md" >}} + +{{% alert title="Note" %}} +If the {{% ctx %}} Interaction Portal is used in your environment, you must also upgrade those flows. +{{% /alert %}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.SingleServerWithoutHA.TryItOut" >}} +[Upgrade Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.5to2024.7.SingleServerWithoutHA.UpgradeApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/_index.md new file mode 100644 index 000000000..4a29d5dca --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/_index.md @@ -0,0 +1,6 @@ +--- +title: "2024.7 to 2024.9" +linkTitle: "2024.7 to 2024.9" +description: "Instructions to upgrade {{% ctx %}} 2024.7 to 2024.9" +weight: 997 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..10ed76d03 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Multiple Server - With HA" +linkTitle: "Multiple Server - With HA" +description: "Upgrade instructions for multiple on-premise servers with high availability (HA)." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..8750d3ba8 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Servers and Load Balancer Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.9/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/multi-server/test-executing-production-flows.md" >}} + +[Application Servers and Load Balancer Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..7f23a7095 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers.md @@ -0,0 +1,79 @@ +--- +title: "Upgrade Application Servers and Load Balancer" +linkTitle: "Upgrade Application Servers and Load Balancer" +description: "Information about upgrading the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Servers and Load Balancer Server from 2024.7 to 2024.9. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used to perform the upgrade from, and copy the following artefacts to a folder on it: + * Cortex Innovation 2024.9 - App Server Install Scripts.zip + * Cortex Innovation 2024.9 - App Services.zip + * Cortex Innovation 2024.9 - Block Packages.zip + +1. Extract the `Cortex Innovation 2024.9 - App Server Install Scripts.zip` file to a folder with the same name. + +## Configure Upgrade Script + +1. In the `Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.ApplicationConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or the values should be changed then use the `Use New Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.9 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.9 - Block Packages.zip" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.9 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.9 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1, 192.168.1.2, 192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server being used for the upgrade. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server being used for the upgrade. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server being used for the upgrade.| + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. If the built-in load balancer is not being used, this should be removed.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. + +## Run Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-application-server/multi-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/multi-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/_index.md new file mode 100644 index 000000000..ec4c6a59d --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Upgrade the Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server." +weight: 40 +--- + +This guide describes how to upgrade the Web Application Server. Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.7 version of Gateway and its prerequisites have already been installed. + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md new file mode 100644 index 000000000..fbbadcc08 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/prerequisites.md @@ -0,0 +1,30 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Upgrade of the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +Please ensure that [Upgrade Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v2024.7 version of Gateway and its prerequisites have already been installed. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation 2024.9 - App Services.zip + * Cortex Innovation 2024.9 - App Server Install Scripts.zip + * Cortex Innovation 2024.9 - Block Packages.zip + * Cortex Innovation 2024.9 - Gateway.zip + * Cortex Innovation 2024.9 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.9 - App Server Install Scripts.zip` file to a folder with the same name. +1. Extract the `Cortex Innovation 2024.9 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Next Steps? + +1. [Upgrade Flow Debugger][] + +[Upgrade Application Servers and Load Balancer]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeApplicationAndLoadBalancerServers" >}} +[Upgrade Flow Debugger]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeDebugger" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md new file mode 100644 index 000000000..e79dc6f38 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger.md @@ -0,0 +1,33 @@ +--- +title: "Upgrade Flow Debugger" +linkTitle: "Upgrade Flow Debugger" +description: "Information about upgrading the Flow Debugger." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Flow Debugger on the Web Application Server from 2024.7 to 2024.9. Please ensure that the [prerequisites][] have been completed before starting this upgrade. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-application-server/single-server/run-upgrade-script.md">}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade Gateway][] + +[prerequisites]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.WebApplicationServerPreqrequisites" >}} +[Upgrade Gateway]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeGateway" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md new file mode 100644 index 000000000..c10bf9752 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway.md @@ -0,0 +1,59 @@ +--- +title: "Upgrade Gateway" +linkTitle: "Upgrade Gateway" +description: "Information about upgrading {{% ctx %}} Gateway from 2024.7 to 2024.9." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.7 to 2024.9. Please ensure that the [Flow Debugger upgrade][] has been completed before starting this upgrade. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-web-application-server/run-gateway-script.md" >}} + +## Republish Packages + {{< alert type="note" title="Note" >}} This only needs to happen for upgrading to this release version as breaking changes were introduced as part of the cleanup of the NServiceBus endpoint and RabbitMQ queues.{{< /alert >}} +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. In the `Package Definitions` grid, select `Is Published` filter option on the `Is Published` column to show all published packages. +1. For each published package version: + * Select the package. + * Click `Unpublish` at the bottom of the `Definition` tab and click `Unpublish` on the confirmation pop-up dialog. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy + * Click `Create New Version` then click `Save` and wait for the new version to be created. + * Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. + * Sometimes the list of published packages in the `Package Definitions` grid disappears. To fix, set the `Is Published` filter in the `Package Definitions` grid to blank option and then set the filter to `Is Published` option again to show all published packages. + +## Delete Old Execution Services + {{< alert type="note" title="Note" >}} This only needs to happen for upgrading to this release version as breaking changes were introduced as part of the cleanup of the NServiceBus endpoint and RabbitMQ queues.{{< /alert >}} + +1. Open a web browser. +1. Navigate to `https://server.domain.com:9080/Explorer`, where `server.domain.com` is the fully qualified domain name of one of the application servers. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration of the original installation. +1. Expand `Cluster` then `Applications` then `Cortex.Innovation.Execution`. +1. For all old execution applications: + * Click on the drop down menu and select `Delete Application`. Confirm application deletion by following the on-screen instructions. + * Give this a few minutes. If the application does not delete: + * Expand `Nodes` + * For each node: + * Expand the node and select the application that matches the engine version number of the application that is being attempted to be deleted. + * Expand each level up to and including `Code Packages`. + * Click on the drop down menu for `Code` and select `Restart`. Confirm application restart by following the on-screen instructions. + * Give this a few minutes. Once all nodes have been restarted the application should be deleted and disappear from the list of applications. + +Repeat the above instructions for the `Flow Debugger`. In step 2 `server.domain.com` is the fully qualified domain name of the web application server. + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Flow Debugger upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.UpgradeDebugger" >}} +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/_index.md new file mode 100644 index 000000000..a43e88369 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/_index.md @@ -0,0 +1,6 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Upgrade instructions for a single on-premise server without high availability (HA)." +weight: 500 +--- diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..de31c3621 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/try-it-out.md @@ -0,0 +1,19 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} after upgrade." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out an upgraded {{% ctx %}} to make sure it is working. Please ensure that both the [Application Server Upgrade][] and [Web Application Server Upgrade][] has been completed before taking these steps. + +{{< section "/upgrade/2024.9/upgrade-web-application-server/test-upgrade.md" >}} + +## Test Executing Production Flows + +{{< section "/upgrade/try-it-out/single-server/test-executing-production-flows.md" >}} + +[Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.UpgradeApplicationServer" >}} +[Web Application Server Upgrade]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-application-server.md new file mode 100644 index 000000000..c2e76965f --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-application-server.md @@ -0,0 +1,37 @@ +--- +title: "Upgrade Application Server" +linkTitle: "Upgrade Application Server" +description: "Information about upgrading the Application Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to upgrade the Application Server components on the server from 2024.7 to 2024.9. + +## Make Installation Artefacts Available + +{{< section "/upgrade/2024.9/upgrade-application-server/single-server/make-installation-artefacts-available.md" >}} + +## Configure Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-application-server/single-server/configure-upgrade-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-application-server/single-server/run-upgrade-script.md" >}} + +## Check Application Services + +{{< section "/upgrade/upgrade-application-server/single-server/check-application-services.md" >}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Upgrade Web Application Server][] + +[Upgrade Web Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.UpgradeWebApplicationServer" >}} + diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-web-application-server.md b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-web-application-server.md new file mode 100644 index 000000000..e4fc5c5ca --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-web-application-server.md @@ -0,0 +1,64 @@ +--- +title: "Upgrade Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server from 2024.7 to 2024.9." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway from 2024.7 to 2024.9. Please ensure that the [Upgrade Application Server][] has been completed before starting this upgrade. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the server: + + * Cortex Innovation 2024.9 - Gateway.zip + * Cortex Innovation 2024.9 - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.9 - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Configure Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-web-application-server/configure-gateway-script.md" >}} + +## Run Upgrade Script + +{{< section "/upgrade/2024.9/upgrade-web-application-server/run-gateway-script.md" >}} + +## Publish New Package Versions + {{< alert type="note" title="Note" >}} This only needs to happen for upgrading to this release version as breaking changes were introduced as part of the cleanup of the NServiceBus endpoint and RabbitMQ queues.{{< /alert >}} +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. For each previously published package version: + * Select the package. + * Click `Create New Version` then click `Save` and wait for the new version to be created. + * Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. + +## Delete Old Execution Service + {{< alert type="note" title="Note" >}} This only needs to happen for upgrading to this release version as breaking changes were introduced as part of the cleanup of the NServiceBus endpoint and RabbitMQ queues.{{< /alert >}} + +1. Open a web browser. +1. Navigate to `https://server.domain.com:9080/Explorer`, where `server.domain.com` is the fully qualified domain name of the server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration of the original installation. +1. Expand `Cluster` then `Applications` then `Cortex.Innovation.Execution`. +1. For all old execution applications: + * Click on the drop down menu and select `Delete Application`. Confirm application deletion by following the on-screen instructions. + * Give this a few minutes. If the application does not delete: + * Expand `Nodes` + * For each node: + * Expand the node and select the application that matches the engine version number of the application that is being attempted to be deleted. + * Expand each level up to and including `Code Packages`. + * Click on the drop down menu for `Code` and select `Restart`. Confirm application restart by following the on-screen instructions. + * Give this a few minutes. Once all nodes have been restarted the application should be deleted and disappear from the list of applications. + + +## Preserve installation files + +{{< section "/preserve-installation-files.md" >}} + +## Next Steps? + +1. [Try It Out][] + +[Try It Out]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.TryItOut" >}} +[Upgrade Application Server]: {{< url path="Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA.UpgradeApplicationServer" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/_index.md new file mode 100644 index 000000000..4d02a4f21 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/_index.md @@ -0,0 +1,6 @@ +--- +title: "Upgrade CORTEX" +linkTitle: "Upgrade CORTEX" +description: "Guides to upgrade {{% ctx %}}" +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/_index.md b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/_index.md new file mode 100644 index 000000000..c28d33a5c --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/_index.md @@ -0,0 +1,6 @@ +--- +title: "Advanced Setup" +linkTitle: "Advanced Setup" +description: "Supporting information about upgrading {{% ctx %}}." +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/ssl-best-practices.md b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/ssl-best-practices.md new file mode 100644 index 000000000..5e6b69e78 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/ssl-best-practices.md @@ -0,0 +1,9 @@ +--- +title: "SSL Best Practices" +linkTitle: "SSL Best Practices" +description: "Information about the recommended security settings for {{% ctx %}} servers." +--- + +# {{% param title %}} + +{{< section "/advanced/ssl-best-practices.md" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/upgrade-flows.md b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/upgrade-flows.md new file mode 100644 index 000000000..149033b99 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-cortex/advanced/upgrade-flows.md @@ -0,0 +1,23 @@ +--- +title: "Upgrade Flows" +linkTitle: "Upgrade Flows" +description: "Information about upgrading flows." +--- + +# {{% param title %}} + +{{% alert title="Note" %}} +Sometimes, between versions of {{% ctx %}}, breaking or non-breaking changes have to be made to blocks. This can cause existing flows to break or not work as expected which requires them to be upgraded to resolve the issues. +{{% /alert %}} + +## Prerequisites + +1. Copy the following artefacts to a folder on a machine: + + * Cortex Innovation 2024.7 - Flows Upgrader.zip + +1. Extract the `Cortex Innovation 2024.7 - Flows Upgrader.zip` zip file to a folder with the same name. + +## Upgrade the flows + +{{< section "/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/_index.md new file mode 100644 index 000000000..8faaea3a2 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/_index.md @@ -0,0 +1,6 @@ +--- +title: "Upgrade Observability" +linkTitle: "Upgrade Observability" +description: "Information about upgrading your observability platform for {{% ctx %}}." +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/cloud/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/_index.md new file mode 100644 index 000000000..4eaa242d6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/_index.md @@ -0,0 +1,6 @@ +--- +title: "Cloud" +linkTitle: "Cloud" +description: "Information about upgrading a cloud-hosted observability platform for {{% ctx %}}." +weight: 500 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/_index.md new file mode 100644 index 000000000..1337f8126 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/_index.md @@ -0,0 +1,6 @@ +--- +title: "Grafana" +linkTitle: "Grafana" +description: "Information about upgrading a cloud-hosted Grafana platform for {{% ctx %}}." +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/prerequisites.md new file mode 100644 index 000000000..d141133bc --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/prerequisites.md @@ -0,0 +1,44 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "The prerequisites required before performing the observability upgrade." +weight: 1 +--- + +# {{% param title %}} + +## Verify Old Version + +1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net` +1. Login to Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex* +1. Click the *Flow Execution Requests* dashboard to open it. +1. Change the time period to be *Last 90 days* and confirm data is present. +1. Make a note of values returned in the Overview tiles, or alternatively take a screenshot of the dashboard, to use later to verify the upgrade. + +## Make Artefacts Available + +1. Download the required artefacts to a folder on your machine: + + * [Promtail 3.0.0][] archive. + * [Promtail Install][] archive. + +1. Extract the downloaded `promtail-windows-amd64.exe` archive to a folder with the same name. +1. Extract the downloaded `Promtail.Install` archive to a folder with the same name. + +## Backup Old Files + +On each Application Server that Promtail is installed on: + +1. Create a folder called `Observability Backups` in a known location. +1. Open File Explorer and navigate to the location where Promtail is running from, e.g. `C:\Promtail`. +1. Copy the `promtail-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1. + +## Next Steps? + +1. [Upgrade Promtail][] + +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[Promtail Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}} +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/try-it-out.md new file mode 100644 index 000000000..f6d53e219 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/try-it-out.md @@ -0,0 +1,48 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out the observability platform after upgrade." +weight: 3 +--- + +# {{% param title %}} + +This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Promtail][] has been completed before taking these steps. + +## Confirm Dashboards Load + +1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net` +1. Login to Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex* +1. Click the *Flow Execution Requests* dashboard to open it. +1. Change the time period to be *Last 90 days* and confirm data is present. +1. Confirm the data from the previous step is similar to the data captured when [verifying the old version][]. + +## Confirm New Data is Processed + +{{% alert title="Note" %}} +Any flow can be used that exists on the system and can be executed. +{{% / alert %}} + +1. Open a web browser and navigate to your installed {{% ctx %}} Gateway URL, e.g. `https://server.domain.com/gateway`, and log in when prompted. +1. Open a flow that you are able to execute on an ad hoc basis. +1. Start the flow. +1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Flow Execution Requests* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Platform Health* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} + +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}} +[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.VerifyOldVersion" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md new file mode 100644 index 000000000..001236749 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md @@ -0,0 +1,75 @@ +--- +title: "Upgrade Promtail" +linkTitle: "Upgrade Promtail" +description: "The steps to upgrade Promtail." +weight: 2 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Promtail installation. Please ensure that the [Prerequisites] for upgrading Observability have been completed before starting this upgrade. + +## Perform Upgrade + +{{% alert title="Note" %}} +These steps will need to be performed on all application servers that host a Promtail service. +{{% / alert %}} + +1. Log in to the application server. +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where Promtail is running from, e.g. `cd C:\Program Data\Cortex\Observability\Promtail`. +1. Remove the current Promtail installation by executing the following command: + + ``` powershell + .\Remove-Promtail.ps1 + ``` + +1. Click *Yes* when prompted for confirmation that you wish to remove the service. +1. Click *OK* when the successful removal of the Promtail service is confirmed. +1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\Program Data\Cortex\Observability\Promtail` +1. Delete the following files from the directory: + + * Install-Promtail.ps1 + * nssm.exe + * Promtail-local-config.yaml + * Promtail-windows-amd64.exe + * Remove-Promtail.ps1 + * Start-Promtail.ps1 + * Stop-Promtail.ps1 + +1. In File Explorer, navigate to the extracted `promtail-windows-amd64.exe` folder created as part of [Make Artefacts Available][]. +1. Copy the `promtail-windows-amd64.exe` file into the folder that Promtail was previously running from, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. In File Explorer, navigate to the extracted `Promtail.Install` folder created as part of [Make Artefacts Available][]. +1. Copy the contents of this location into the folder that Promtail was previously running from, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. Open `promtail-local-config.yaml` in a text editor: + + * Update the *filename* property under *positions* to be the value found in the [backed up][] version. + * Update the *url* property under *clients* to be the value found in the [backed up][] version. + * Save the new `promtail-local-config.yaml` file. + +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where the Promtail files have been copied to, e.g. `cd C:\Program Data\Cortex\Observability\Promtail`. +1. Install Promtail by executing the following command: + + ``` powershell + .\Install-Promtail.ps1 + ``` + +1. Start the Promtail service by executing the following command: + + ``` powershell + .\Start-Promtail.ps1 + ``` + +1. Check that the Promtail service has installed and started correctly: + * Open Services.msc from the Start menu. + * Locate the *Promtail* service and confirm that it is *Running*. + +## Next Steps? + +1. [Try it out][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.BackupOldFiles" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.MakeArtefactsAvailable" >}} +[Prerequisites]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.Prerequisites" >}} +[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/_index.md new file mode 100644 index 000000000..83fd0b271 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/_index.md @@ -0,0 +1,6 @@ +--- +title: "Grafana" +linkTitle: "Grafana" +description: "Information about upgrading the default Grafana dashboards for your observability platform." +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md new file mode 100644 index 000000000..09b163023 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md @@ -0,0 +1,36 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out the observability platform after upgrading the dashboards." +weight: 3 +--- + +# {{% param title %}} + +## Confirm New Dashboards Display Data + +{{% alert title="Note" %}} +Any flow can be used that exists on the system and can be executed. +{{% / alert %}} + +1. Open a web browser and navigate to your installed {{% ctx %}} Gateway URL, e.g. `https://server.domain.com/gateway`, and log in when prompted. +1. Open a flow that you are able to execute on an ad hoc basis. +1. Start the flow. +1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Flow Execution Requests* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Platform Health* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} + +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}} +[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.VerifyOldVersion" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md new file mode 100644 index 000000000..6f95386b5 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md @@ -0,0 +1,40 @@ +--- +title: "Upgrade Dashboards" +linkTitle: "Upgrade Dashboards" +description: "Information about upgrading your Grafana dashboards." +weight: 1 +--- + +# {{% param title %}} + +This guide describes how to upgrade the default dashboards that are provided for your observability platform. + +## Download the Default Dashboards + +1. Download [Grafana.Dashboards.zip][] archive containing the {{% ctx %}} Innovation default dashboards. +1. Extract the content of the downloaded archive to a suitable location. + +## Import New Dashboards + +1. Log in to your configured Grafana with a user that has the *Admin* role. +1. Go to *Dashboards* via the menu on the left sidebar. +1. Click the *New* button and select *Import* from the drop-down menu. +1. Click the *Upload JSON file* button. +1. Locate the `Flow Execution Requests.json` file [extracted][] from the downloaded `Grafana.Dashboards.zip`. +1. Select the file and click *Open*. +{{% alert title="Note" %}} +You will receive warnings that *A dashboard or folder with the same name already exists* and *Dashboard named 'Flow Execution Requests' in folder 'Cortex' has the same UID*. These can be ignored. +{{% / alert %}} + +1. Select the folder in Grafana you wish the dashboard to be saved in, e.g. *Cortex*. +1. Select your configured Loki data source from the dropdown menu. +1. Click *Import (Overwrite)*. +1. Repeat steps 2 - 9 for the `Platform Health.json` file. + +## Next Steps? + +1. [Try it out][] + +[extracted]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.Download" >}} +[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaDashboardsZip" >}} +[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.TryItOut" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/_index.md new file mode 100644 index 000000000..4078c1304 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/dashboards/_index.md @@ -0,0 +1,6 @@ +--- +title: "Dashboards" +linkTitle: "Dashboards" +description: "Information about upgrading the default dashboards provided for your observability platform." +weight: 1000 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/_index.md new file mode 100644 index 000000000..59f2ef8fd --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/_index.md @@ -0,0 +1,6 @@ +--- +title: "On-Premise" +linkTitle: "On-Premise" +description: "Information about upgrading an on-premise observability platform for {{% ctx %}}." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/_index.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/_index.md new file mode 100644 index 000000000..0b777445d --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/_index.md @@ -0,0 +1,6 @@ +--- +title: "Grafana" +linkTitle: "Grafana" +description: "Information about upgrading an on-premise Grafana platform for {{% ctx %}}." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/prerequisites.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/prerequisites.md new file mode 100644 index 000000000..1a7dbf3e1 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/prerequisites.md @@ -0,0 +1,60 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "The prerequisites required before performing the observability upgrade." +weight: 1 +--- + +# {{% param title %}} + +## Verify Old Version + +1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000` +1. Make a note of the version number under the login prompt. +1. Login to Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex* +1. Click the *Flow Execution Requests* dashboard to open it. +1. Change the time period to be *Last 90 days* and confirm data is present. +1. Make a note of values returned in the Overview tiles, or alternatively take a screenshot of the dashboard, to use later to verify the upgrade. + +## Make Artefacts Available + +1. Download the required artefacts to a folder on your machine: + + * [Grafana 10.4.1][] Standalone Windows Binaries archive. + * [Grafana Loki 3.0.0][] archive. + * [Grafana Loki Install][] archive. + * [Promtail 3.0.0][] archive. + * [Promtail Install][] archive. + +1. Extract the downloaded `grafana-enterprise-10.4.1.windows-amd64` archive to a folder with the same name. +1. Extract the downloaded `loki-windows-amd64.exe` archive to a folder with the same name. +1. Extract the downloaded `Grafana.Loki.Install` archive to a folder with the same name. +1. Extract the downloaded `promtail-windows-amd64.exe` archive to a folder with the same name. +1. Extract the downloaded `Promtail.Install` archive to a folder with the same name. + +## Backup Old Files + +1. On the server that Grafana and Loki is installed on, create a folder called `Observability Backups` in a known location. +1. Open File Explorer and navigate to the location that Grafana was previously installed to, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana\conf`. +1. Copy the `custom.ini` file and save it to the `Observability Backups` folder created at step 1. +1. Copy the `defaults.ini` file and save it to the `Observability Backups` folder created at step 1. +1. In File Explorer, navigate to the location that Loki is running from, e.g. `C:\Loki\`. +1. Copy the `loki-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1. +1. On each Application Server that Promtail is installed on: + + 1. Create a folder called `Observability Backups` in a known location. + 1. Open File Explorer and navigate to the location that Promtail is running from, e.g. `C:\Promtail`. + 1. Copy the `promtail-local-config.yaml` file and save it to the `Observability Backups` folder created at step 7.1. + +## Next Steps? + +1. [Upgrade Grafana][] + +[Grafana 10.4.1]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaWebApp.10.4.1.Windows" >}} +[Grafana Loki 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaLoki.3.0.0.GrafanaLokiInstallZip" >}} +[Grafana Loki Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaLokiInstallZip" >}} +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[Promtail Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}} +[Upgrade Grafana]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeGrafana" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/try-it-out.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/try-it-out.md new file mode 100644 index 000000000..3f46dd3c6 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/try-it-out.md @@ -0,0 +1,54 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out the observability platform after upgrade." +weight: 5 +--- + +# {{% param title %}} + +This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Promtail][] has been completed before taking these steps. + +## Confirm Grafana Upgrade + +1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000`. +1. Identify the version number under the login prompt. +1. Confirm the version has updated to be 10.4.1. + +## Confirm Dashboards Load + +1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000` +1. Login to Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex* +1. Click the *Flow Execution Requests* dashboard to open it. +1. Change the time period to be *Last 90 days* and confirm data is present. +1. Confirm the data from the previous step is similar to the data captured when [verifying the old version][]. + +## Confirm New Data is Processed + +{{% alert title="Note" %}} +Any flow can be used that exists on the system and can be executed. +{{% / alert %}} + +1. Open a web browser and navigate to your installed {{% ctx %}} Gateway URL, e.g. `https://server.domain.com/gateway`, and log in when prompted. +1. Open a flow that you are able to execute on an ad hoc basis. +1. Start the flow. +1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Flow Execution Requests* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Platform Health* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} + +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradePromtail" >}} +[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.VerifyOldVersion" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md new file mode 100644 index 000000000..c60d9a272 --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md @@ -0,0 +1,31 @@ +--- +title: "Upgrade Grafana" +linkTitle: "Upgrade Grafana" +description: "The steps to upgrade Grafana." +weight: 2 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Grafana installation. Please ensure that the [Prerequisites] for upgrading Observability have been completed before starting this upgrade. + +## Perform Upgrade + +1. Log in to the server hosting your Grafana website. +1. Open Services.msc from the Start menu. +1. Locate the *Grafana* service and stop it by right-clicking on the service and selecting *Stop*. +1. In File Explorer, navigate to the `grafana-enterprise-10.4.1.windows-amd64` folder created as part of [Make Artefacts Available][]. +1. Open the `grafana-v10.4.1` subfolder. +1. Copy the contents of this folder into the Grafana install location, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana`, and click `Replace the files in the destination` when prompted. +1. Copy the [backed up][] `custom.ini` and `defaults.ini` files into the Grafana install configuration location, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana\conf`, and click `Replace the files in the destination` when prompted. +1. Open Services.msc from the Start menu. +1. Locate the *Grafana* service and start it by right-clicking on the service and selecting *Start*. + +## Next Steps? + +1. [Upgrade Loki][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.BackupOldFiles" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Prerequisites]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.Prerequisites" >}} +[Upgrade Loki]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeLoki" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md new file mode 100644 index 000000000..8da4dd9db --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md @@ -0,0 +1,93 @@ +--- +title: "Upgrade Loki" +linkTitle: "Upgrade Loki" +description: "The steps to upgrade Loki." +weight: 3 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Loki installation. Please ensure that the [Grafana Upgrade] has been completed before starting this upgrade. + +## Perform Upgrade + +1. Log in to the server hosting your Loki service. +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where Loki is running from, e.g. `cd C:\Program Data\Cortex\Observability\Loki`. +1. Remove the current Loki installation by executing the following command: + + ``` powershell + .\Remove-Loki.ps1 + ``` + +1. Click *Yes* when prompted for confirmation that you wish to remove the service. +1. Click *OK* when the successful removal of the Loki service is confirmed. +1. Open a File Explorer and navigate to the folder where Loki was running from, e.g. `C:\Program Data\Cortex\Observability\Loki`. +1. Delete the following files from the directory: + + * Install-Loki.ps1 + * loki-local-config.yaml + * loki-windows-amd64.exe + * nssm.exe + * Remove-Loki.ps1 + * Start-Loki.ps1 + * Stop-Loki.ps1 + +1. In File Explorer, navigate to the extracted `loki-windows-amd64.exe` folder created as part of [Make Artefacts Available][]. +1. Copy the `loki-windows-amd64.exe` file into the folder that Loki was previously running from, e.g. `C:\Program Data\Cortex\Observability\Loki`. +1. In File Explorer, navigate to the extracted `Grafana.Loki.Install` folder created as part of [Make Artefacts Available][]. +1. Copy the contents of this location into the folder that Loki was previously running from, e.g. `C:\Program Data\Cortex\Observability\Loki`. +1. Open the new `loki-local-config.yaml` file in a text editor and compare against the [backed up][] version. If there are differences between the two files in the *schema_config* > *configs* section: + + 1. In the new file, change the date next to `- from` to be today's date. + 1. Copy the old config section from the backup and add it immediately under *configs* and before the existing `- from ` line ensuring that formatting (including indentations) remain identical to that which is used in the new file. + + The new *schema_config* should result in something similar to: + + ```yaml + schema_config: + configs: + - from: 2020-10-24 + store: boltdb-shipper + object_store: filesystem + schema: v11 + index: + prefix: index_ + period: 24h + - from: 2024-08-29 + store: tsdb + object_store: filesystem + schema: v13 + index: + prefix: index_ + period: 24h + ``` + + 1. Save the new `loki-local-config.yaml` file. + +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where the Loki files have been copied to, e.g. `cd C:\Program Data\Cortex\Observability\Loki`. +1. Install Loki by executing the following command: + + ``` powershell + .\Install-Loki.ps1 + ``` + +1. Start the Loki service by executing the following command: + + ``` powershell + .\Start-Loki.ps1 + ``` + +1. Check that the Loki service has installed and started correctly: + * Open Services.msc from the Start menu. + * Locate the *Loki* service and confirm that it is *Running*. + +## Next Steps? + +1. [Upgrade Promtail][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.BackupOldFiles" >}} +[Grafana Upgrade]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeGrafana" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradePromtail" >}} diff --git a/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md new file mode 100644 index 000000000..267e2e10b --- /dev/null +++ b/content/en/docs/2024.9/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md @@ -0,0 +1,75 @@ +--- +title: "Upgrade Promtail" +linkTitle: "Upgrade Promtail" +description: "The steps to upgrade Promtail." +weight: 4 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Promtail installation. Please ensure that the [Loki Upgrade][] has been completed before starting this upgrade. + +## Perform Upgrade + +{{% alert title="Note" %}} +These steps will need to be performed on all application servers that host a Promtail service. +{{% / alert %}} + +1. Log in to the application server. +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where Promtail is running from, e.g. `cd C:\Program Data\Cortex\Observability\Promtail`. +1. Remove the current Promtail installation by executing the following command: + + ``` powershell + .\Remove-Promtail.ps1 + ``` + +1. Click *Yes* when prompted for confirmation that you wish to remove the service. +1. Click *OK* when the successful removal of the Promtail service is confirmed. +1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\Program Data\Cortex\Observability\Promtail` +1. Delete the following files from the directory: + + * Install-Promtail.ps1 + * nssm.exe + * Promtail-local-config.yaml + * Promtail-windows-amd64.exe + * Remove-Promtail.ps1 + * Start-Promtail.ps1 + * Stop-Promtail.ps1 + +1. In File Explorer, navigate to the extracted `promtail-windows-amd64.exe` folder created as part of [Make Artefacts Available][]. +1. Copy the `promtail-windows-amd64.exe` file into the folder that Promtail was previously running from, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. In File Explorer, navigate to the extracted `Promtail.Install` folder created as part of [Make Artefacts Available][]. +1. Copy the contents of this location into the folder that Promtail was previously running from, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. Open the new `promtail-local-config.yaml` in a text editor: + + * Update the *filename* property under *positions* to be the value found in the [backed up][] version. + * Update the *url* property under *clients* to be the value found in the [backed up][] version. + * Save the new `promtail-local-config.yaml` file. + +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where the Promtail files have been copied to, e.g. `cd C:\Program Data\Cortex\Observability\Promtail`. +1. Install Promtail by executing the following command: + + ``` powershell + .\Install-Promtail.ps1 + ``` + +1. Start the Promtail service by executing the following command: + + ``` powershell + .\Start-Promtail.ps1 + ``` + +1. Check that the Promtail service has installed and started correctly: + * Open Services.msc from the Start menu. + * Locate the *Promtail* service and confirm that it is *Running*. + +## Next Steps? + +1. [Try it out][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.BackupOldFiles" >}} +[Loki Upgrade]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeLoki" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.TryItOut" >}} diff --git a/content/en/docs/2024.9/Overview/_index.md b/content/en/docs/2024.9/Overview/_index.md new file mode 100644 index 000000000..408a100e8 --- /dev/null +++ b/content/en/docs/2024.9/Overview/_index.md @@ -0,0 +1,87 @@ +--- +title: "Overview" +linkTitle: "Overview" +description: "Find out what the {{% ctx %}} platform is, what it can do, and how you can get started?" +weight: 2 +--- + +## What is {{% ctx %}}? + +### Low-code automation + +{{% ctx %}} is a **[low-code][Studio]**, **automation and orchestration platform**, that enables organisations to graphically **capture** and **automate** anything from simple **tasks**, to interactive **workflows**, to complex IT and business **processes** that span the entire organisation. + +### Enterprise-grade + +Evolved from process and control engineering for mission-critical environments, {{% ctx %}} provides **enterprise-grade** functionality to cover the **full automation lifecycle**; enabling **rapid delivery** of automation **[on-premise][]** or in the **cloud**, from inception to production, **without** the need for **software development experience**. + +### Built for everyone + +{{% ctx %}} is being **built for everyone**, not just software developers, with the goal of **removing barriers** to entry and putting your people at the heart of your automation. + +### Comprehensive functionality + +With a **[comprehensive set of functionality][Blocks]** and interfaces with **3rd party systems** available **out-of-the-box**, it's **[quick and easy to get started][Getting Started]** on your automation journey. + +## What can it do? + +### Deliver quickly + +Using {{% ctx %}}, global organisations have been able to **increase** their **capacity, velocity, quality, efficiency, agility** and **transform** their business and IT **operations in months**. + +### For diverse sets of use cases + +{{% ctx %}} has been deployed for a diverse set of **[use cases][]**, including: + +* Lights out **monitoring** and **management** of fixed-line telephony networks +* Data center **provisioning** +* **Patching** of servers +* IT service **diagnostics** +* **Swivel chair** operations +* Employee **onboarding** and offboarding +* Animal welfare **compliance checks** + +### Resulting in successful outcomes + +{{% ctx %}} has resulted in many successful **outcomes**, including: + +* Increased **revenue** +* Increased **profit** +* **Redeployment** of skilled employees +* Reduction in **MTTR** +* Reduction in **average handling time** + +### Accelerate your digital transformation + +Wherever you are on your automation journey and whatever you are trying to achieve, small or large, simple or complex, {{% ctx %}} can help **accelerate a successful transformation of your operations**. + +## How do I get started? + +||| +|-----------|-------------| +|**[Getting Started][Getting Started]**|Install {{% ctx %}} and start your automation journey today.| +|**[Guides][]**|Learn how to use the various components that make up the {{% ctx %}} platform.| +|**[Tutorials][]**|Explore all of the tutorials for the {{% ctx %}} platform.| +|**[Reference][]**|Browse through the reference documentation, including details about APIs, blocks, data types, exceptions.| +|**[FAQs][]**|Find the answers to your questions.| +|**[Videos][]**|View a range of videos about the {{% ctx %}} platform, automation, strategies and methodologies, as well as industry specific content.| +|**[Engage With Us][Engage With Us]**|Let us help you to get started by reaching out to us. | + +[FAQs]: {{< url path="Cortex.Faqs.MainDoc" >}} + +[Getting Started]: {{< url path="Cortex.GettingStarted.MainDoc" >}} +[on-premise]: {{< url path="Cortex.GettingStarted.OnPremise.MainDoc" >}} + +[Guides]: {{< url path="Cortex.Guides.MainDoc" >}} +[Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} + +[Tutorials]: {{< url path="Cortex.Tutorials.MainDoc" >}} + +[Reference]: {{< url path="Cortex.Reference.MainDoc" >}} +[Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Engage With Us]: {{< url path="Cortex.Website.EngageWithUs.MainDoc" >}} + +[use cases]: {{< url path="Cortex.Website.UseCases.MainDoc" >}} + +[Videos]: {{< url path="Cortex.YouTube.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/APIs/_index.md b/content/en/docs/2024.9/Reference/APIs/_index.md new file mode 100644 index 000000000..c1ff26a3d --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/_index.md @@ -0,0 +1,6 @@ +--- +title: "APIs" +linkTitle: "APIs" +description: "This section includes all reference documentation for APIs." +weight: 10 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-gateway/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-gateway/_index.md new file mode 100644 index 000000000..d9bbeaffa --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-gateway/_index.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Gateway" +linkTitle: "CORTEX Gateway" +description: "This section includes all reference documentation for the APIs exposed by {{% ctx %}} Gateway." +weight: 1 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/_index.md new file mode 100644 index 000000000..d5185d02e --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/_index.md @@ -0,0 +1,6 @@ +--- +title: "CORTEX Innovation" +linkTitle: "CORTEX Innovation" +description: "This section includes all reference documentation for the APIs exposed by the {{% ctx %}} Innovation platform." +weight: 300 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/_index.md new file mode 100644 index 000000000..35082aa64 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Core Application" +linkTitle: "Core Application" +description: "This section includes all reference documentation for the APIs exposed by the Core Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/_index.md new file mode 100644 index 000000000..e144554b5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "This section includes all reference documentation for the APIs exposed by the Core Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/api-gateway-service/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/api-gateway-service/_index.md new file mode 100644 index 000000000..c41056aee --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/api-gateway-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "API Gateway Service" +linkTitle: "API Gateway Service" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by the API Gateway Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/licence-management-service/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/licence-management-service/_index.md new file mode 100644 index 000000000..d83ca2a97 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/licence-management-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Licence Management Service" +linkTitle: "Licence Management Service" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by the Licence Management Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/package-management-service/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/package-management-service/_index.md new file mode 100644 index 000000000..0e21b7ced --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/package-management-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Package Management Service" +linkTitle: "Package Management Service" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by the Package Management Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/provisioning-service/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/provisioning-service/_index.md new file mode 100644 index 000000000..3d4300820 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/core-application/services/provisioning-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Provisioning Service" +linkTitle: "Provisioning Service" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by the Provisioning Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/_index.md new file mode 100644 index 000000000..9e97eb21a --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Execution Application" +linkTitle: "Execution Application" +description: "This section includes all reference documentation for the APIs exposed by the Execution Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/_index.md new file mode 100644 index 000000000..058daec0c --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "This section includes all reference documentation for the APIs exposed by the Execution Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/execution-service/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/execution-service/_index.md new file mode 100644 index 000000000..b25716e02 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-innovation/execution-application/services/execution-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Execution Service" +linkTitle: "Execution Service" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by the Execution Service." +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/APIs/cortex-studio/_index.md b/content/en/docs/2024.9/Reference/APIs/cortex-studio/_index.md new file mode 100644 index 000000000..930596c18 --- /dev/null +++ b/content/en/docs/2024.9/Reference/APIs/cortex-studio/_index.md @@ -0,0 +1,9 @@ +--- +title: "CORTEX Studio" +linkTitle: "CORTEX Studio" +type: swagger +description: "This section includes all reference documentation for the APIs exposed by {{% ctx %}} Studio." +weight: 100 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Dictionaries/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/_index.md new file mode 100644 index 000000000..00ec618d3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/_index.md @@ -0,0 +1,5 @@ +--- +title: "Dictionaries" +linkTitle: "Dictionaries" +description: "Blocks related to working with Dictionaries." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Dictionaries/add-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/add-item/_index.md new file mode 100644 index 000000000..b2b2a09a8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/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 dictionary." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Dictionaries/add-item/add-item-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/add-item/add-item-with-key-block-3.md new file mode 100644 index 000000000..698f90fda --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/add-item/add-item-with-key-block-3.md @@ -0,0 +1,172 @@ +--- +title: "Add Item With Key" +linkTitle: "Add Item With Key" +description: "Adds an item to a Dictionary with the specified key." +--- + +{{< figure src="/blocks/Cortex_Blocks_Dictionaries_AddItem_AddItemWithKeyBlock_3.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Dictionaries/contains-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/_index.md new file mode 100644 index 000000000..18d91f743 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-and-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-and-value-block-3.md new file mode 100644 index 000000000..03feaaaa9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyAndValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-key-block-3.md new file mode 100644 index 000000000..bb89338fe --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-item-with-value-block-3.md new file mode 100644 index 000000000..b10ad335f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-keys-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-keys-block-3.md new file mode 100644 index 000000000..28239d5a6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithKeysBlock_3.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/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-values-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/contains-item/contains-items-with-values-block-3.md new file mode 100644 index 000000000..f15ec6f13 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithValuesBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-count/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-count/_index.md new file mode 100644 index 000000000..ec65cd646 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/get-count/get-count-of-all-items-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-count/get-count-of-all-items-block-3.md new file mode 100644 index 000000000..ea5be2e69 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetCount_GetCountOfAllItemsBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-count/get-count-of-items-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-count/get-count-of-items-with-value-block-3.md new file mode 100644 index 000000000..149466793 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetCount_GetCountOfItemsWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-count/get-counts-of-items-with-values-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-count/get-counts-of-items-with-values-block-3.md new file mode 100644 index 000000000..a95a114ef --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetCount_GetCountsOfItemsWithValuesBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-item/_index.md new file mode 100644 index 000000000..9a60abac1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/get-item/get-all-items-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-item/get-all-items-block-3.md new file mode 100644 index 000000000..694e4c54b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetItem_GetAllItemsBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-item/get-item-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-item/get-item-with-key-block-3.md new file mode 100644 index 000000000..ca6314730 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetItem_GetItemWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-item/get-items-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-item/get-items-with-key-block-3.md new file mode 100644 index 000000000..e72a62b5c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetItem_GetItemsWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/get-key/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-key/_index.md new file mode 100644 index 000000000..d0504c442 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/get-key/get-all-keys-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/get-key/get-all-keys-block-3.md new file mode 100644 index 000000000..3486432e2 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_GetKey_GetAllKeysBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/_index.md new file mode 100644 index 000000000..a516b96dd --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-all-items-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-all-items-block-3.md new file mode 100644 index 000000000..cbcf93b83 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveAllItemsBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-key-block-3.md new file mode 100644 index 000000000..5fc75bc2f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-item-with-value-block-3.md new file mode 100644 index 000000000..aa9ff35fb --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-key-block-3.md new file mode 100644 index 000000000..70c10e14b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-keys-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-keys-block-3.md new file mode 100644 index 000000000..e91bcb477 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeysBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-value-block-3.md new file mode 100644 index 000000000..3775948b6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-values-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/remove-item/remove-items-with-values-block-3.md new file mode 100644 index 000000000..37712ef00 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValuesBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/_index.md new file mode 100644 index 000000000..56379859a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-all-items-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-all-items-block-3.md new file mode 100644 index 000000000..67b6571ce --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetAllItemsBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-item-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-item-with-key-block-3.md new file mode 100644 index 000000000..6d984389a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-item-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-item-with-value-block-3.md new file mode 100644 index 000000000..bbd0a76a2 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-key-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-key-block-3.md new file mode 100644 index 000000000..132557d01 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeyBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-keys-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-keys-block-3.md new file mode 100644 index 000000000..49388153c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeysBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-value-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-value-block-3.md new file mode 100644 index 000000000..482d394a7 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValueBlock_3.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/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-values-block-3.md b/content/en/docs/2024.9/Reference/Blocks/Dictionaries/set-item/set-items-with-values-block-3.md new file mode 100644 index 000000000..51771bfc0 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValuesBlock_3.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/2024.9/Reference/Blocks/Exceptions/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/_index.md new file mode 100644 index 000000000..517a2760b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/_index.md new file mode 100644 index 000000000..0b363a866 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-block.md new file mode 100644 index 000000000..6e454a488 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionBlock.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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-message-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-message-block.md new file mode 100644 index 000000000..fe0107c23 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessageBlock.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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-messages-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-messages-block.md new file mode 100644 index 000000000..bd37e0708 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessagesBlock.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() {}` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether any of the [Messages][Messages Property] are 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`). | +| [PropertyEmptyException][] | Thrown when [Messages][Messages Property] contains no items. | +| [PropertyNullException][] | Thrown when [Messages][Messages 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][]. + +### Null or empty Message in Messages + +If any message in [Messages][Messages 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][]. + +[Messages Property]: {{< ref "#messages" >}} +[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" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-name-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-name-block.md new file mode 100644 index 000000000..83f461a9a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-name-block.md @@ -0,0 +1,228 @@ +--- +title: "Handle Block Exception Matching Type Name" +linkTitle: "Handle Block Exception Matching Type Name" +description: "Handles any exception thrown by the block it is connected to that matches a specified type name." +--- + +{{< figure src="/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNameBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-names-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-block-exception/handle-block-exception-matching-type-names-block.md new file mode 100644 index 000000000..a6f198f1d --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNamesBlock.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() {}` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether any of the [Type Names][TypeNames Property] are 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`). | +| [PropertyContainsNullOrEmptyItemException][] | Thrown when any Type Name in [Type Names][TypeNames Property] is `null` or empty (i.e. `""`). | +| [PropertyEmptyException][] | Thrown when [Type Names][TypeNames Property] contains no items. | +| [PropertyNullException][] | Thrown when [Type Names][TypeNames 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][]. + +[TypeNames Property]: {{< ref "#type-names" >}} +[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" >}} +[PropertyContainsNullOrEmptyItemException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyContainsNullOrEmptyItemException.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" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.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/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/_index.md new file mode 100644 index 000000000..9a2fdbacc --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/_index.md @@ -0,0 +1,5 @@ +--- +title: "Handle Flow Exception(s)" +linkTitle: "Handle Flow Exception(s)" +description: "Handle exceptions not handled by any Handle Block Exception or Handle Workspace Exception blocks." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/handle-flow-exception-workspace-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/handle-flow-exception-workspace-block.md new file mode 100644 index 000000000..77d9d9a97 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-flow-exception/handle-flow-exception-workspace-block.md @@ -0,0 +1,143 @@ +--- +title: "Handle Flow Exception" +linkTitle: "Handle Flow Exception" +description: "Handles any unhandled exception within the Flow." +--- + +{{< figure src="/blocks/Cortex_Blocks_Exceptions_HandleFlowException_HandleFlowExceptionWorkspaceBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Exceptions/handle-workspace-exception/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-workspace-exception/_index.md new file mode 100644 index 000000000..bfe98fb7b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Exceptions/handle-workspace-exception/handle-workspace-exception-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/handle-workspace-exception/handle-workspace-exception-block.md new file mode 100644 index 000000000..822923d3c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_HandleWorkspaceException_HandleWorkspaceExceptionBlock.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/2024.9/Reference/Blocks/Exceptions/rethrow-exception/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/rethrow-exception/_index.md new file mode 100644 index 000000000..2867ac09a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Exceptions/rethrow-exception/rethrow-exception-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/rethrow-exception/rethrow-exception-block.md new file mode 100644 index 000000000..1289c161d --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_RethrowException_RethrowExceptionBlock.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/2024.9/Reference/Blocks/Exceptions/throw-exception/_index.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/throw-exception/_index.md new file mode 100644 index 000000000..6825cb935 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Exceptions/throw-exception/throw-new-flow-exception-block.md b/content/en/docs/2024.9/Reference/Blocks/Exceptions/throw-exception/throw-new-flow-exception-block.md new file mode 100644 index 000000000..31007f815 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Exceptions_ThrowException_ThrowNewFlowExceptionBlock.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/2024.9/Reference/Blocks/Files-And-Folders/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/_index.md new file mode 100644 index 000000000..f42a0941a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/check-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/check-file/_index.md new file mode 100644 index 000000000..e5fb6edbb --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/check-file/check-file-exists-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/check-file/check-file-exists-block.md new file mode 100644 index 000000000..2a00b2f51 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CheckFile_CheckFileExistsBlock.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/2024.9/Reference/Blocks/Files-And-Folders/check-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/check-folder/_index.md new file mode 100644 index 000000000..4ae62e559 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/check-folder/check-folder-exists-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/check-folder/check-folder-exists-block.md new file mode 100644 index 000000000..182858896 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CheckFolder_CheckFolderExistsBlock.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/2024.9/Reference/Blocks/Files-And-Folders/copy-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-file/_index.md new file mode 100644 index 000000000..71e54f21e --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/copy-file/copy-file-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-file/copy-file-block.md new file mode 100644 index 000000000..0542f41e9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFileBlock.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/2024.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md new file mode 100644 index 000000000..c54a51005 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-file/copy-files-block.md @@ -0,0 +1,215 @@ +--- +title: "Copy Files" +linkTitle: "Copy Files" +description: "Copies files at the specified file paths to the given destination path." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFilesBlock.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. `""`). | +| | Any file path in [File Paths][FilePaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/_index.md new file mode 100644 index 000000000..0b4717a91 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folder-block.md new file mode 100644 index 000000000..c759f552f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md new file mode 100644 index 000000000..f1f10885c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/copy-folders-block.md @@ -0,0 +1,496 @@ +--- +title: "Copy Folders" +linkTitle: "Copy Folders" +description: "Copies folders at the specified folder paths to the given destination path." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFoldersBlock.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. `""`). | +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/duplicate-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/copy-folder/duplicate-folder-block.md new file mode 100644 index 000000000..0cc8ffb25 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CopyFolder_DuplicateFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/create-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/create-folder/_index.md new file mode 100644 index 000000000..91e4e4279 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/create-folder/create-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/create-folder/create-folder-block.md new file mode 100644 index 000000000..ef24a457f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md new file mode 100644 index 000000000..e055574d7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/create-folder/create-folders-block.md @@ -0,0 +1,115 @@ +--- +title: "Create Folders" +linkTitle: "Create Folders" +description: "Create folders at the specified folder paths." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFoldersBlock.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. `""`). | +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/delete-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-file/_index.md new file mode 100644 index 000000000..e4e10375e --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/delete-file/delete-file-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-file/delete-file-block.md new file mode 100644 index 000000000..a3596286b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFileBlock.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/2024.9/Reference/Blocks/Files-And-Folders/delete-file/delete-files-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-file/delete-files-block.md new file mode 100644 index 000000000..1f775355a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFilesBlock.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. `""`). | +| | Any file path in [File Paths][FilePaths Property] is duplicated. | +| | 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/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/_index.md new file mode 100644 index 000000000..03f110087 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folder-block.md new file mode 100644 index 000000000..c10eede1b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md new file mode 100644 index 000000000..99c2b2b7d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/delete-folder/delete-folders-block.md @@ -0,0 +1,176 @@ +--- +title: "Delete Folders" +linkTitle: "Delete Folders" +description: "Deletes folders at the specified folder paths." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFoldersBlock.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. `""`). | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/get-file-information/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-file-information/_index.md new file mode 100644 index 000000000..e2945e03a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/get-file-information/get-file-information-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-file-information/get-file-information-block.md new file mode 100644 index 000000000..f788b2e41 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_GetFileInformation_GetFileInformationBlock.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/2024.9/Reference/Blocks/Files-And-Folders/get-folder-content/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-folder-content/_index.md new file mode 100644 index 000000000..4c4696535 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/get-folder-content/get-folder-content-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-folder-content/get-folder-content-block.md new file mode 100644 index 000000000..80f16e84f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_GetFolderContent_GetFolderContentBlock.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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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/2024.9/Reference/Blocks/Files-And-Folders/get-folder-information/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-folder-information/_index.md new file mode 100644 index 000000000..9b3213535 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/get-folder-information/get-folder-information-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/get-folder-information/get-folder-information-block.md new file mode 100644 index 000000000..8f53d6999 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_GetFolderInformation_GetFolderInformationBlock.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/2024.9/Reference/Blocks/Files-And-Folders/move-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-file/_index.md new file mode 100644 index 000000000..72624ef3e --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/move-file/move-file-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-file/move-file-block.md new file mode 100644 index 000000000..f28976562 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFileBlock.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/2024.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md new file mode 100644 index 000000000..b99f6d675 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-file/move-files-block.md @@ -0,0 +1,214 @@ +--- +title: "Move Files" +linkTitle: "Move Files" +description: "Moves files at the specified file paths to the given destination path." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFilesBlock.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. `""`). | +| | Any file path in [File Paths][FilePaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/move-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-folder/_index.md new file mode 100644 index 000000000..facdb6dda --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/move-folder/move-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-folder/move-folder-block.md new file mode 100644 index 000000000..b36340253 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md new file mode 100644 index 000000000..da4312d0d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/move-folder/move-folders-block.md @@ -0,0 +1,494 @@ +--- +title: "Move Folders" +linkTitle: "Move Folders" +description: "Moves folders at the specified folder paths to the given destination path." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFoldersBlock.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. `""`). | +| | Any folder path in [Folder Paths][FolderPaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/read-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/read-file/_index.md new file mode 100644 index 000000000..172a52744 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/read-file/read-all-lines-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/read-file/read-all-lines-block.md new file mode 100644 index 000000000..5b4b345a7 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllLinesBlock.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/2024.9/Reference/Blocks/Files-And-Folders/read-file/read-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/read-file/read-all-text-block.md new file mode 100644 index 000000000..60f4e5c2c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllTextBlock.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/2024.9/Reference/Blocks/Files-And-Folders/rename-folder/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/rename-folder/_index.md new file mode 100644 index 000000000..e4b6c16b7 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/rename-folder/rename-folder-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/rename-folder/rename-folder-block.md new file mode 100644 index 000000000..0595cb931 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_RenameFolder_RenameFolderBlock.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/2024.9/Reference/Blocks/Files-And-Folders/search-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/search-file/_index.md new file mode 100644 index 000000000..5bdc44c30 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/search-file/search-file-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/search-file/search-file-block.md new file mode 100644 index 000000000..0362dca0f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFileBlock.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 LiteralText, 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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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/2024.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md new file mode 100644 index 000000000..d5129d3dc --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/search-file/search-files-block.md @@ -0,0 +1,527 @@ +--- +title: "Search Files" +linkTitle: "Search Files" +description: "Searches files at the specified file paths for a matching search pattern." +--- + +{{< figure src="/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFilesBlock.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 LiteralText, 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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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. `""`).| +| | Any file path in [File Paths][FilePaths Property] is duplicated. | +| | 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" >}} +[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/2024.9/Reference/Blocks/Files-And-Folders/write-file/_index.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/write-file/_index.md new file mode 100644 index 000000000..bcadbe7f5 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Files-And-Folders/write-file/write-all-lines-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/write-file/write-all-lines-block.md new file mode 100644 index 000000000..f492aae35 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllLinesBlock.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/2024.9/Reference/Blocks/Files-And-Folders/write-file/write-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Files-And-Folders/write-file/write-all-text-block.md new file mode 100644 index 000000000..842f74cf8 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllTextBlock.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/2024.9/Reference/Blocks/Lists/Get-Count/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Count/_index.md new file mode 100644 index 000000000..6e11b63ca --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-all-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-all-items-block-2.md new file mode 100644 index 000000000..5b9210bcd --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetCount_GetCountOfAllItemsBlock_2.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/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-value-block-2.md new file mode 100644 index 000000000..7b68af599 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetCount_GetCountOfItemsWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-values-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Count/get-count-of-items-with-values-block-2.md new file mode 100644 index 000000000..9571a09f0 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetCount_GetCountsOfItemsWithValuesBlock_2.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/2024.9/Reference/Blocks/Lists/Get-Index/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Index/_index.md new file mode 100644 index 000000000..f76c2f371 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/Get-Index/get-index-of-item-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Index/get-index-of-item-with-value-block-2.md new file mode 100644 index 000000000..b21ce2717 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetIndex_GetIndexOfItemWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/Get-Index/get-indexes-of-items-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/Get-Index/get-indexes-of-items-with-value-block-2.md new file mode 100644 index 000000000..46cc20c8e --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetIndex_GetIndexesOfItemsWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/_index.md new file mode 100644 index 000000000..81c3fb421 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/add-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/_index.md new file mode 100644 index 000000000..46346dea3 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/add-item/add-item-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-item-at-beginning-block-2.md new file mode 100644 index 000000000..2127a3d94 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/add-item/add-item-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-item-at-end-block-2.md new file mode 100644 index 000000000..38c27bb97 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/add-item/add-item-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-item-at-index-block-2.md new file mode 100644 index 000000000..af7c4a13b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/add-item/add-items-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-items-at-beginning-block-2.md new file mode 100644 index 000000000..f8a90c90c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemsAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/add-item/add-items-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-items-at-end-block-2.md new file mode 100644 index 000000000..d447abfea --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemsAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/add-item/add-items-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/add-item/add-items-at-index-block-2.md new file mode 100644 index 000000000..07914cdbd --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_AddItem_AddItemsAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/contains-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/contains-item/_index.md new file mode 100644 index 000000000..30f4fc7df --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/contains-item/contains-item-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/contains-item/contains-item-with-value-block-2.md new file mode 100644 index 000000000..7f1b5c433 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_ContainsItem_ContainsItemWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/contains-item/contains-items-with-values-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/contains-item/contains-items-with-values-block-2.md new file mode 100644 index 000000000..2786f60c7 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_ContainsItem_ContainsItemsWithValuesBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/_index.md new file mode 100644 index 000000000..cb3bb09ff --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/get-item/get-item-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-item-at-beginning-block-2.md new file mode 100644 index 000000000..23a5e294c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-item-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-item-at-end-block-2.md new file mode 100644 index 000000000..97d639aaa --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-item-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-item-at-index-block-2.md new file mode 100644 index 000000000..69d663f1b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-items-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-items-at-beginning-block-2.md new file mode 100644 index 000000000..75dc649e9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemsAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-items-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-items-at-end-block-2.md new file mode 100644 index 000000000..5ee1c5db0 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemsAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-items-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-items-at-index-block-2.md new file mode 100644 index 000000000..c48e83d76 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/get-item/get-items-at-indexes-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/get-item/get-items-at-indexes-block-2.md new file mode 100644 index 000000000..9ae92f53e --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexesBlock_2.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() {}` | + +### Items + +The [Items][Items Property] at the specified [Indexes][Indexes Property] of [List][List Property]. + +[Items][Items Property] will be in the order they are defined in [Indexes][Indexes 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 | +|----------|----------| +| [DuplicateValueException][] | Thrown when [Indexes][Indexes Property] contains duplicate values. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Indexes][Indexes Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Indexes][Indexes Property] contains no values. | +| | Thrown when any index in [Indexes][Indexes Property] is less than `0` or greater than the count of items in [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" >}} +[Indexes Property]: {{< ref "#indexes" >}} +[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" >}} + +[DuplicateValueException]: {{< url path="Cortex.Reference.Exceptions.Lists.DuplicateValueException.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" >}} +[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/2024.9/Reference/Blocks/Lists/remove-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/_index.md new file mode 100644 index 000000000..233ff40fb --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Lists/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 list." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-all-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-all-items-block-2.md new file mode 100644 index 000000000..de5db2ef2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-all-items-block-2.md @@ -0,0 +1,121 @@ +--- +title: "Remove All Items" +linkTitle: "Remove All Items" +description: "Removes all items from a List." +--- + +{{< figure src="/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveAllItemsBlock_2.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Lists/remove-item/remove-duplicate-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-duplicate-items-block-2.md new file mode 100644 index 000000000..9763d5c85 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveDuplicateItemsBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-beginning-block-2.md new file mode 100644 index 000000000..f863a6ab9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-end-block-2.md new file mode 100644 index 000000000..96dc25d90 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-item-at-index-block-2.md new file mode 100644 index 000000000..558e0390f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-item-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-item-with-value-block-2.md new file mode 100644 index 000000000..e63608b42 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-beginning-block-2.md new file mode 100644 index 000000000..9b06f2d6f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-end-block-2.md new file mode 100644 index 000000000..7b1f535a6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-index-block-2.md new file mode 100644 index 000000000..57e59601c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-indexes-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-at-indexes-block-2.md new file mode 100644 index 000000000..5ae474585 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexesBlock_2.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() {}` | + +## 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 [Indexes][Indexes Property] contains duplicate values. | +| [PropertyNullException][] | Thrown when [List][List Property] or [Indexes][Indexes Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Indexes][Indexes Property] contains no values. | +| | Thrown when any index in [Indexes][Indexes Property] is less than `0` or greater than the count of items in [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" >}} +[Indexes Property]: {{< ref "#indexes" >}} + +[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" >}} +[DuplicateValueException]: {{< url path="Cortex.Reference.Exceptions.Lists.DuplicateValueException.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" >}} +[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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-with-value-block-2.md new file mode 100644 index 000000000..f64d98740 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-with-value-block-2.md @@ -0,0 +1,156 @@ +--- +title: "Remove Items With Value" +linkTitle: "Remove Items With Value" +description: "Removes all items matching a value from a List." +--- + +{{< figure src="/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValueBlock_2.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Lists/remove-item/remove-items-with-values-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/remove-item/remove-items-with-values-block-2.md new file mode 100644 index 000000000..407501cf9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValuesBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/_index.md new file mode 100644 index 000000000..1a848c4be --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Lists/set-item/set-all-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-all-items-block-2.md new file mode 100644 index 000000000..0c6cde53a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetAllItemsBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-item-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-item-at-beginning-block-2.md new file mode 100644 index 000000000..4dcfab374 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-item-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-item-at-end-block-2.md new file mode 100644 index 000000000..10c267ac4 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-item-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-item-at-index-block-2.md new file mode 100644 index 000000000..4aca09744 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-item-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-item-with-value-block-2.md new file mode 100644 index 000000000..f4f278cbd --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsWithValueBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-items-at-beginning-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-at-beginning-block-2.md new file mode 100644 index 000000000..c7636b076 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsAtBeginningBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-items-at-end-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-at-end-block-2.md new file mode 100644 index 000000000..d9bb48327 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsAtEndBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-items-at-index-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-at-index-block-2.md new file mode 100644 index 000000000..ee33c69b4 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexBlock_2.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/2024.9/Reference/Blocks/Lists/set-item/set-items-at-indexes-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-at-indexes-block-2.md new file mode 100644 index 000000000..3de4ba4e9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexesBlock_2.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() {}` | + +## 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 [Indexes][Indexes Property] contains duplicate values. | +| [PropertyItemCountException][] | Thrown when the count of items in [New Values][NewValues Property] and the count of items in [Indexes][Indexes Property] are not the same. | +| [PropertyNullException][] | Thrown when [List][List Property] or [New Values][NewValues Property] or [Indexes][Indexes Property] is `null`. | +| [PropertyValueOutOfRangeException][] | Thrown when [Indexes][Indexes Property] contains no values. | +| | Thrown when any index in [Indexes][Indexes Property] is less than `0` or greater than the count of items in [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" >}} +[NewValues Property]: {{< ref "#new-values" >}} +[Indexes Property]: {{< ref "#indexes" >}} + +[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" >}} +[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" >}} +[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" >}} +[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/2024.9/Reference/Blocks/Lists/set-item/set-items-with-value-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-with-value-block-2.md new file mode 100644 index 000000000..a7fb27054 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-with-value-block-2.md @@ -0,0 +1,149 @@ +--- +title: "Set Items With Value" +linkTitle: "Set Items With Value" +description: "Sets all items matching a value in a List to a new value." +--- + +{{< figure src="/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValueBlock_2.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Lists/set-item/set-items-with-values-block-2.md b/content/en/docs/2024.9/Reference/Blocks/Lists/set-item/set-items-with-values-block-2.md new file mode 100644 index 000000000..8100b1aee --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Lists_SetItem_SetItemsWithValuesBlock_2.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/2024.9/Reference/Blocks/PowerShell/_index.md b/content/en/docs/2024.9/Reference/Blocks/PowerShell/_index.md new file mode 100644 index 000000000..7bb3eb21b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/PowerShell/execute-powershell-script/_index.md b/content/en/docs/2024.9/Reference/Blocks/PowerShell/execute-powershell-script/_index.md new file mode 100644 index 000000000..abc8da99e --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/PowerShell/execute-powershell-script/execute-powershell-script-block-1.md b/content/en/docs/2024.9/Reference/Blocks/PowerShell/execute-powershell-script/execute-powershell-script-block-1.md new file mode 100644 index 000000000..710c76d7b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_PowerShell_ExecutePowerShellScript_ExecutePowerShellScriptBlock_1.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"}}`

In this example `($)PowerShellSessionDetails` has been set up using the following [Expression][]:

`new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))` | `($)Credentials` is a variable of type [PowerShellWinRMSessionDetails][]

The [Password][UserCredentials Password] property within [UserCredentials][] of the [PowerShellWinRMSessionDetails][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession`, with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` will be set to the type [IList][]<[dynamic][]> | +| [Records][Records Property] | `($)Records`, with no value | `($)Records` will be set to the type [Records][] | + +#### Result + +Running the [Script][Script Property] results in the variable `($)Outputs` being updated to the following: + +```json +[ + "This is the content of the file located on the host the script is running on." +] +``` + +It also results in the variable `($)Records` being updated to the following: + +```json +{ + "ErrorRecords": [], + "WarningRecords": [], + "DebugRecords": [], + "ProgressRecords": [], + "VerboseRecords": [], + "InformationRecords": [] +} +``` + +After the [Script][Script Property] has been executed, the session will be closed, for more information see [Closing Sessions][]. + +*** + +### Execute a Script with Parameters 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."` + +In this example assume the following variables have been set before the script has been executed: + +- `($)FilePath` with the value `"Get-Content \"C:\\Folder\\Example.txt\""` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Script][Script Property] | `($)Script` with value `"Get-Content $FilePath"` | `($)Script` is a variable of type [String][] | +| [Parameters][Parameters Property] | `($)Parameters` with value `{"FilePath": ($)FilePath"}` | `($)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"}}`

In this example `($)PowerShellSessionDetails` has been set up using the following [Expression][]:

`new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))` | `($)Credentials` is a variable of type [PowerShellWinRMSessionDetails][]

The [Password][UserCredentials Password] property within [UserCredentials][] of the [PowerShellWinRMSessionDetails][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession`, with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` will be set to the type [IList][]<[dynamic][]> | +| [Records][Records Property] | `($)Records`, with no value | `($)Records` will be set to the type [Records][] | + +#### Result + +Running the [Script][Script Property] results in the variable `($)Outputs` being updated to the following: + +```json +[ + "This is the content of the file located on the host the script is running on." +] +``` + +It also results in the variable `($)Records` being updated to the following: + +```json +{ + "ErrorRecords": [], + "WarningRecords": [], + "DebugRecords": [], + "ProgressRecords": [], + "VerboseRecords": [], + "InformationRecords": [] +} +``` + +After the [Script][Script Property] has been executed, the session will be closed, for more information see [Closing Sessions][]. + +*** + +### Execute a Script that returns Records 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\"; $DebugPreference = 'Continue'; Write-Warning 'Warning'; Write-Debug 'Debug'; Write-Information 'Information'; Write-Verbose 'Verbose' -Verbose; Get-Error"` | `($)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"}}`

In this example `($)PowerShellSessionDetails` has been set up using the following [Expression][]:

`new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))` | `($)Credentials` is a variable of type [PowerShellWinRMSessionDetails][]

The [Password][UserCredentials Password] property within [UserCredentials][] of the [PowerShellWinRMSessionDetails][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession`, with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Outputs][Outputs Property] | `($)Outputs`, with no value | `($)Outputs` will be set to the type [IList][]<[dynamic][]> | +| [Records][Records Property] | `($)Records`, with no value | `($)Records` will be set to the type [Records][] | + +#### Result + +Running the [Script][Script Property] results in the variable `($)Outputs` being updated to the following: + +```json +[ + "This is the content of the file located on the host the script is running on." +] +``` + +It also results in the variable `($)Records` being updated to the following: + +```json +{ + "ErrorRecords": [ + "The term 'Get-Error' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again." + ], + "WarningRecords": [ + "Warning" + ], + "DebugRecords": [ + "Debug" + ], + "ProgressRecords": [ + "parent = -1 id = 0 act = Preparing modules for first use. stat = cur = pct = -1 sec = -1 type = Completed" + ], + "VerboseRecords": [ + "Verbose" + ], + "InformationRecords": [ + "Information" + ] +} +``` + +After the [Script][Script Property] has been executed, the session will be closed, for more information see [Closing Sessions][]. + +*** + +## Properties + +### Script + +The [Script][Script Property] which will be executed on the [Host][ServerDetails Host] provided within the [PowerShell Session Details][PowerShell Session Details Property], this can be a script, a file path of a script on the host, or a cmdlet. + +Note that to execute a script using its file path, the file path must accessible to the [Host][ServerDetails Host]. + +||| +|----------|----------| +| Data Type | [EncryptableText][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Parameters + +The parameters to be passed into the [Script][Script Property]. + +||| +|----------|----------| +| Data Type | [IDictionary][]<[String][], [dynamic][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | No value (defaults to `null`) | + +### PowerShell Session Details + +The [PowerShell Session Details][PowerShell Session Details Property] object that includes all of the information required to connect and maintain a PowerShell Session. This property contains all of the information in relation to the server the script will be executed on, these are: + +- [ServerDetails][PowerShellSessionDetails Server Details] +- [Credentials][] +- [PsConfiguration][] + +||| +|----------|----------| +| Data Type | [PowerShellSessionDetails][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)PowerShellSessionDetails` with no value | + +### Close Session + +[Close Session][Close Session Property] can be specified to choose whether the session on the [Host][ServerDetails Host] is closed or is kept open for use on subsequent Execute PowerShell Script blocks, this defaults to `false` if left blank, please see [Closing Sessions][] for more information. + +||| +|----------|----------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +### Outputs + +IList<dynamic> of outputs from the execution of the [Script][Script Property]. + +||| +|----------|----------| +| Data Type | [IList][]<[dynamic][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Outputs` with no value | + +### Records + +The Records object that includes the error, warning, debug, progress, verbose, and information records from the execution of the script or cmdlet. + +||| +|----------|----------| +| Data Type | [Records][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Records` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [PSRemotingException][] | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] is invalid (e.g. host does not exist or invalid characters/whitespace). | +| | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] does not have PSRemoting configured correctly. | +| | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] is a host name; is being accessed through a private or domain network, and Kerberos authentication is disabled on the host's WinRM service or the server's WinRM client. | +| | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] is a host name; is being accessed through a public network, and its name is not on the server's WinRM TrustedHosts list. | +| | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] is an IP Address; is being accessed through any network (i.e. public, private or domain), and is not on the server's WinRM TrustedHosts list. | +| | Thrown when the [Host][ServerDetails Host] within the [PowerShell Session Details][PowerShell Session Details Property] is an IP Address being accessed through any network (i.e. public, private or domain) or a host name being accessed through a public network, and Negotiate authentication is disabled on the host's WinRM service. | +| | Thrown when the [Port][ServerDetails Port] within the [PowerShell Session Details][PowerShell Session Details Property] is invalid. | +| | Thrown when the [UseSsl][ServerDetails UseSsl] is `false` and the specified [Port][ServerDetails Port] within the [PowerShell Session Details][PowerShell Session Details Property] is not configured for HTTP protocols. | +| | Thrown when the [UseSsl][ServerDetails UseSsl] is `true` and the specified [Port][ServerDetails Port] within the [PowerShell Session Details][PowerShell Session Details Property] is not configured for HTTPS protocols. | +| | Thrown when the [UseSsl][ServerDetails UseSsl] is `true` and the host does not have a valid certificate configured. | +| | Thrown when the [Domain][UserCredentials Domain], [Username][UserCredentials Username], or [Password][UserCredentials Password] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is invalid. | +| | Thrown when the [Domain][UserCredentials Domain] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null` or empty and is required. | +| | Thrown when the user does not have the correct user permissions to execute PowerShell scripts or cmdlets on the [Host][ServerDetails Host]. | +| | Thrown when the [PsConfiguration][] within the [PowerShell Session Details][PowerShell Session Details Property] is invalid or is not configured on the [Host][ServerDetails Host]. | +| [PSException][] | Thrown when the [Script][Script Property] contains any unexpected or invalid tokens. | +| | Thrown when the [Script][Script Property] is missing any necessary tokens. | +| [PropertyNullException][] | Thrown when the [Script][Script Property] is `null`. | +| | Thrown when [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| | Thrown when the [ServerDetails][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| | Thrown when the [Host][ServerDetails Host] within the [ServerDetails][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| | Thrown when the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| | Thrown when the [Username][UserCredentials Username] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| | Thrown when the [Password][UserCredentials Password] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is `null`. | +| [PropertyEmptyException][] | Thrown when [Script][Script Property] is empty. | +| | Thrown when the [Host][ServerDetails Host] within the [ServerDetails][] within the [PowerShell Session Details][PowerShell Session Details Property] is empty. | +| | Thrown when the [Username][UserCredentials Username] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is empty. | +| | Thrown when the [Password][UserCredentials Password] in the [Credentials][] within the [PowerShell Session Details][PowerShell Session Details Property] is empty. | +| [PropertyValueOutOfRangeException][] | Thrown when the [Port][ServerDetails Port] within the [ServerDetails][] within the [PowerShell Session Details][PowerShell Session Details Property] is below `1` or above `65535`. | + +## Remarks + +### Opening Sessions + +The Execute PowerShell Script block automatically handles creating and opening session for the specified [PowerShell Session Details][PowerShell 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 used the block runs. + +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 [Script][Script Property] has been executed. + +For information on how to open a session, please see [Opening Sessions][]. + +### Known Limitations + +None + +[Script Property]: {{< ref "#script" >}} +[PowerShell Session Details Property]: {{< ref "#powershell-session-details" >}} +[Parameters Property]: {{< ref "#parameters" >}} +[Close Session Property]: {{< ref "#close-session" >}} +[Outputs Property]: {{< ref "#outputs" >}} +[Records Property]: {{< ref "#records" >}} + +[Opening Sessions]: {{< ref "#opening-sessions" >}} +[Closing Sessions]: {{< ref "#closing-sessions" >}} + +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[ServerDetails]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.MainDoc" >}} +[ServerDetails Host]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Host" >}} +[ServerDetails Port]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.Port" >}} +[ServerDetails UseSsl]: {{< url path="Cortex.Reference.DataTypes.SessionDetails.ServerDetails.UseSsl" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[UserCredentials Domain]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Domain" >}} +[UserCredentials Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[UserCredentials Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[PowerShellWinRMSessionDetails]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellWinRMSessionDetails.MainDoc" >}} +[Records]: {{< url path="Cortex.Reference.DataTypes.PowerShell.Records.MainDoc" >}} + +[PowerShellSessionDetails]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellSessionDetails.MainDoc" >}} +[PowerShellSessionDetails Server Details]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellSessionDetails.ServerDetails" >}} +[Credentials]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellSessionDetails.Credentials" >}} +[PsConfiguration]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellSessionDetails.PsConfiguration" >}} + +[PSException]: {{< url path="Cortex.Reference.Exceptions.PowerShell.PSException.MainDoc" >}} +[PSRemotingException]: {{< url path="Cortex.Reference.Exceptions.PowerShell.PSRemotingException.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" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/_index.md new file mode 100644 index 000000000..414eb632e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/_index.md @@ -0,0 +1,5 @@ +--- +title: "Convert To" +linkTitle: "Convert To" +description: "Convert text to a different format (e.g. `\"lowercase\"`, `\"UPPERCASE\"`, `\"Title Case\"`, `\"camelCase\"`, `\"PascalCase\"`)." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-camel-case-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-camel-case-block.md new file mode 100644 index 000000000..d63ef328a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-camel-case-block.md @@ -0,0 +1,120 @@ +--- +title: "Convert To Camel Case" +linkTitle: "Convert To Camel Case" +description: "Converts text to camel case (e.g. `\"camelCase\"`)." +--- + +{{< figure src="/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToCamelCaseBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Text/Convert-To/convert-to-lower-case-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-lower-case-block.md new file mode 100644 index 000000000..f9eb6e2d0 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_ConvertTo_ConvertToLowerCaseBlock.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/2024.9/Reference/Blocks/Text/Convert-To/convert-to-pascal-case-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-pascal-case-block.md new file mode 100644 index 000000000..cce527f40 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_ConvertTo_ConvertToPascalCaseBlock.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/2024.9/Reference/Blocks/Text/Convert-To/convert-to-title-case-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-title-case-block.md new file mode 100644 index 000000000..b3d013e36 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_ConvertTo_ConvertToTitleCaseBlock.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/2024.9/Reference/Blocks/Text/Convert-To/convert-to-upper-case-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Convert-To/convert-to-upper-case-block.md new file mode 100644 index 000000000..3f1effcb6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_ConvertTo_ConvertToUpperCaseBlock.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/2024.9/Reference/Blocks/Text/Get-Index/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/Get-Index/_index.md new file mode 100644 index 000000000..b1f69b98a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/Get-Index/get-index-of-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Get-Index/get-index-of-text-block.md new file mode 100644 index 000000000..8b860d2ee --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetIndex_GetIndexOfTextBlock.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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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/2024.9/Reference/Blocks/Text/Get-Index/get-indexes-of-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Get-Index/get-indexes-of-text-block.md new file mode 100644 index 000000000..a973e520d --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetIndex_GetIndexesOfTextBlock.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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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/2024.9/Reference/Blocks/Text/Get-Length/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/Get-Length/_index.md new file mode 100644 index 000000000..0602a8e34 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/Get-Length/get-length-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/Get-Length/get-length-block.md new file mode 100644 index 000000000..216193d6a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetLength_GetLengthBlock.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/2024.9/Reference/Blocks/Text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/_index.md new file mode 100644 index 000000000..cfd3af806 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/add-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/add-text/_index.md new file mode 100644 index 000000000..bafeeb0f4 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/add-text/add-text-after-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/add-text/add-text-after-index-block.md new file mode 100644 index 000000000..01aff80cf --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_AddText_AddTextAfterIndexBlock.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/2024.9/Reference/Blocks/Text/add-text/add-text-at-beginning-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/add-text/add-text-at-beginning-block.md new file mode 100644 index 000000000..9bc8f3ed2 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_AddText_AddTextAtBeginningBlock.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/2024.9/Reference/Blocks/Text/add-text/add-text-at-end-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/add-text/add-text-at-end-block.md new file mode 100644 index 000000000..604cd2d67 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_AddText_AddTextAtEndBlock.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/2024.9/Reference/Blocks/Text/add-text/add-text-before-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/add-text/add-text-before-index-block.md new file mode 100644 index 000000000..03f569a5f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_AddText_AddTextBeforeIndexBlock.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/2024.9/Reference/Blocks/Text/contains-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/_index.md new file mode 100644 index 000000000..a39909591 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/contains-text/contains-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/contains-all-text-block.md new file mode 100644 index 000000000..e369d9766 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_ContainsText_ContainsAllTextBlock.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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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() {}` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether items in [Texts To Find][TextsToFind Property] should be interpreted as a LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Texts To Find][TextsToFind 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.LiteralText` 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 | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether each text in [Texts To Find][TextsToFind 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 All Text + +The result of the contains all text check. + +If all of the texts in [Texts To Find][TextsToFind Property] are 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 | `($)ContainsAllText` 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`). | +| [PropertyNullException][] | Thrown when [Texts To Find][TextsToFind Property] is `null`. | +| [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 one or more items in [Texts To Find][TextsToFind Property] are 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 All Text][ContainsAllText Property] property is set to `false`. + +### Null or empty Texts To Find + +If [Texts To Find][TextsToFind Property] is empty or contains any `null` or empty (i.e. `""`) text, the variable specified in the [Contains All Text][ContainsAllText 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" >}} +[TextsToFind Property]: {{< ref "#texts-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[ContainsAllText Property]: {{< ref "#contains-all-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" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.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" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.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/2024.9/Reference/Blocks/Text/contains-text/contains-any-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/contains-any-text-block.md new file mode 100644 index 000000000..35cf47be0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/contains-any-text-block.md @@ -0,0 +1,261 @@ +--- +title: "Contains Any Text" +linkTitle: "Contains Any Text" +description: "Checks if text contains any of the texts in a given set of texts." +--- + +{{< figure src="/blocks/Cortex_Blocks_Text_ContainsText_ContainsAnyTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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() {}` | + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether items in [Texts To Find][TextsToFind Property] should be interpreted as a LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Texts To Find][TextsToFind 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.LiteralText` 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 | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to determine whether each text in [Texts To Find][TextsToFind 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 Any Text + +The result of the contains any text check. + +If any of the texts in [Texts To Find][TextsToFind 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 | `($)ContainsAnyText` 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`). | +| [PropertyNullException][] | Thrown when [Texts To Find][TextsToFind Property] is `null`. | +| [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 one or more items in [Texts To Find][TextsToFind Property] are 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 Any Text][ContainsAnyText Property] property is set to `false`. + +### Null or empty Texts To Find + +If [Texts To Find][TextsToFind Property] is empty or only contains `null` or empty (i.e. `""`) text, the variable specified in the [Contains Any Text][ContainsAnyText 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" >}} +[TextsToFind Property]: {{< ref "#texts-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[ContainsAnyText Property]: {{< ref "#contains-any-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" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.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" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.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/2024.9/Reference/Blocks/Text/contains-text/contains-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/contains-text-block.md new file mode 100644 index 000000000..5d43abc66 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/contains-text/contains-text-block.md @@ -0,0 +1,258 @@ +--- +title: "Contains Text" +linkTitle: "Contains Text" +description: "Checks if text contains another text." +--- + +{{< figure src="/blocks/Cortex_Blocks_Text_ContainsText_ContainsTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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 LiteralText, 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.LiteralText` | `($)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.LiteralText` | `($)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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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.LiteralText` 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 | `LiteralText` | + +### 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/2024.9/Reference/Blocks/Text/decode-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/decode-text/_index.md new file mode 100644 index 000000000..fc6653945 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/decode-text/decode-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/decode-text/decode-text-block.md new file mode 100644 index 000000000..afde31ce1 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_DecodeText_DecodeTextBlock.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/2024.9/Reference/Blocks/Text/encode-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/encode-text/_index.md new file mode 100644 index 000000000..38ce0b2f7 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/encode-text/encode-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/encode-text/encode-text-block.md new file mode 100644 index 000000000..1b5d720a1 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_EncodeText_EncodeTextBlock.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/2024.9/Reference/Blocks/Text/find-and-remove-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/_index.md new file mode 100644 index 000000000..f11296cc6 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md new file mode 100644 index 000000000..2086bbac2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-all-text-block.md @@ -0,0 +1,349 @@ +--- +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/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveAllTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindAndRemoveText.FindAndRemoveAllTextBlock)

+ +## Description + +Finds and removes all occurrences of [Text To Find][TextToFind Property] from a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a LiteralText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Remove all occurrences when there are multiple matches + +This example will find and remove 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to `" quick brown fox jumps over{{% nbsp %}}{{% nbsp %}}lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Remove all occurrences when there is a single match + +This example will find and remove 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to `" quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Remove all occurrences when there are no matches + +This example will find and remove all occurrences of `"cat"` 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 `{"startsWith": "", "contains": "cat", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "cat", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Results + +`"The quick brown fox jumps over the lazy dog."` does not contain an occurrence of `"cat"`. Therefore, `($)Text` is not updated and remains as `"The quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and remove all occurrences of [Text To Find][TextToFind Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query used to find and remove all matching occurrences from [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +## 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 the execution time of any search done to find all occurrences of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Output Text | The value of the [Text][Text Property] after executing the block. \* | +\* *DEFAULT* indicates that nothing has been found and removed in [Text][Text Property], and that [Text][Text Property] is the same as was initially provided. + +Please note that these examples all perform a search which has at most one valid match in the text. + +#### SearchOptions.LiteralText + +These examples find and remove all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | + +#### SearchOptions.PatternMatching + +These examples find and remove all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `"*"` | `""` | +| `"The"` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"*"` | `""` | +| `"The"` | `"*"` | `""` | `""` | +| `"The"` | `""` | `"*"` | `""` | +| `"*"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"*"` | `""` | +| `"*"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `""` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"*"` | `""` | +| `"*"` | `"*"` | `""` | `""` | +| `"*"` | `""` | `"*"` | `""` | +| `"*"` | `""` | `""` | `""` | +| `""` | `"quick"` | `"*"` | `"The "` | +| `""` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `""` | `"*"` | `"*"` | `""` | +| `""` | `"*"` | `""` | `""` | +| `""` | `""` | `"*"` | `""` | + +#### SearchOptions.Regex + +These examples find and remove all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `".*"` | `""` | +| `"The"` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `".*"` | `""` | +| `"The"` | `".*"` | `""` | `""` | +| `"The"` | `""` | `".*"` | `""` | +| `".*"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `".*"` | `""` | +| `".*"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `""` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `".*"` | `""` | +| `".*"` | `".*"` | `""` | `""` | +| `".*"` | `""` | `".*"` | `""` | +| `".*"` | `""` | `""` | `""` | +| `""` | `"quick"` | `".*"` | `"The "` | +| `""` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `""` | `".*"` | `".*"` | `""` | +| `""` | `".*"` | `""` | `""` | +| `""` | `""` | `".*"` | `""` | + +### 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 Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), or [Text To Find][TextToFind Property] is `null`; no operation is performed and the [Text][Text Property] remains unchanged. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not considered as part of the matches for [Text to Find][TextToFind Property] when determining what to remove; see [Advanced Examples][]. + +### Text To Find is not present + +If [Text To Find][TextToFind 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 Find][TextToFind Property] removed and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[ComparisonType Property]: {{}} +[SearchOptions Property]: {{}} +[Text Property]: {{}} +[TextToFind Property]: {{}} + +[Input]: {{}} +[InputOutput]: {{}} + +[Equality]: {{}} +[ComparisonTypes]: {{}} +[Ordinal]: {{}} +[OrdinalIgnoreCase]: {{}} +[Pattern Matching Syntax]: {{}} +[Regex Syntax]: {{}} + +[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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md new file mode 100644 index 000000000..d4f941c7c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-remove-text/find-and-remove-text-block.md @@ -0,0 +1,394 @@ +--- +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/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveTextBlock.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 Find][TextToFind Property] from a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a LiteralText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Remove the first Occurrence of text + +This example will find and remove 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to `" quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Remove the second Occurrence of text + +This example will find and remove the second 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `2` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence `"the"`. Therefore, the variable `($)Text` will be updated to `"The quick brown fox jumps over{{% nbsp %}}{{% nbsp %}}lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Remove the last Occurrence of text + +This example will find and remove 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence `"the"`. The second occurrence is also the last occurrence, and therefore, the variable `($)Text` will be updated to `"The quick brown fox jumps over{{% nbsp %}}{{% nbsp %}}lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Remove an invalid Occurrence of text + +This example will find and remove the third occurrence of `"The"`, which is not present, 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `3` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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 the text (`"The quick brown fox jumps over the lazy dog."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. There is no match for the third occurrence. Therefore, the variable `($)Text` will be not be updated and remains as `"The quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and remove the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query used to find and remove the specified matching occurrence from [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Occurrence + +The [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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +## 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 the execution time of any search done to find the specific occurrence of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Occurrence][Occurrence Property] | `1` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Output Text | The value of the [Text][Text Property] after executing the block. \* | +\* *DEFAULT* indicates that nothing has been found and removed in [Text][Text Property], and that [Text][Text Property] is the same as was initially provided. + +Please note that these examples all perform a search which has at most one valid match in the text. + +#### SearchOptions.LiteralText + +These examples find and remove the first occurrence from [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | + +#### SearchOptions.PatternMatching + +These examples find and remove the first occurrence from [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `"*"` | `""` | +| `"The"` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"*"` | `""` | +| `"The"` | `"*"` | `""` | `""` | +| `"The"` | `""` | `"*"` | `""` | +| `"*"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"*"` | `""` | +| `"*"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `""` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"*"` | `""` | +| `"*"` | `"*"` | `""` | `""` | +| `"*"` | `""` | `"*"` | `""` | +| `"*"` | `""` | `""` | `""` | +| `""` | `"quick"` | `"*"` | `"The "` | +| `""` | `"*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `""` | `"*"` | `"*"` | `""` | +| `""` | `"*"` | `""` | `""` | +| `""` | `""` | `"*"` | `""` | + +#### SearchOptions.Regex + +These examples find and remove the first occurrence from [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `" quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The{{% nbsp %}}{{% nbsp %}}brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick{{% nbsp %}}{{% nbsp %}}fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `".*"` | `""` | +| `"The"` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `".*"` | `""` | +| `"The"` | `".*"` | `""` | `""` | +| `"The"` | `""` | `".*"` | `""` | +| `".*"` | `"quick"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `".*"` | `""` | +| `".*"` | `"quick"` | `""` | `" brown fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `""` | `"brown"` | `" fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `".*"` | `""` | +| `".*"` | `".*"` | `""` | `""` | +| `".*"` | `""` | `".*"` | `""` | +| `".*"` | `""` | `""` | `""` | +| `""` | `"quick"` | `".*"` | `"The "` | +| `""` | `".*"` | `"brown"` | `" fox jumps over the lazy dog."` | +| `""` | `".*"` | `".*"` | `""` | +| `""` | `".*"` | `""` | `""` | +| `""` | `""` | `".*"` | `""` | + +### 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 Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), or [Text To Find][TextToFind Property] is `null`; no operation is performed and the [Text][Text Property] remains unchanged. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not considered as part of the matches for [Text to Find][TextToFind Property] when determining what to remove; see [Advanced Examples][]. + +### Text To Find is not present + +If [Text To Find][TextToFind 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 Find][TextToFind Property] removed and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[Text Property]: {{}} +[TextToFind Property]: {{}} +[Occurrence Property]: {{}} +[SearchOptions Property]: {{}} +[ComparisonType Property]: {{}} + +[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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/_index.md new file mode 100644 index 000000000..f9038379b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md new file mode 100644 index 000000000..c498f9338 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-all-text-block.md @@ -0,0 +1,370 @@ +--- +title: "Find And Replace All Text" +linkTitle: "Find And Replace All Text" +description: "Finds and replaces all occurrences of a text in a given text." +--- + +{{< figure src="/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceAllTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindAndReplaceText.FindAndReplaceAllTextBlock)

+ +## Description + +Finds and replaces all occurrences of [Text To Find][TextToFind 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 LiteralText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Replace all occurrences when there are multiple matches + +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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText` with value `"a"`| `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Text` will be updated to `"a quick brown fox jumps over a lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Replace all occurrences when there is a single match + +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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText` with value `"a"`| `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to `"a quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Replace all occurrences when there are no matches + +This example will find and replace all occurrences of `"cat"` 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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "cat", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "cat", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText` with value `"a"`| `($)ReplacementText` is a variable of type [String][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | + +#### Results + +`"The quick brown fox jumps over the lazy dog."` does not contain an occurrence of `"cat"`. Therefore, `($)Text` is not updated and remains as `"The quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and replace all occurrences of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query used to find and replace all matching occurrences in [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Replacement Text + +The [Replacement Text][ReplacementText Property] used to replace all occurrences of [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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +## 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 the execution time of any search done to find all occurrences of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | +| [Replacement Text][ReplacementText Property] | `"ReplacementText"` | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Output Text | The value of the [Text][Text Property] after executing the block. \* | +\* *DEFAULT* indicates that nothing has been found and replaced in [Text][Text Property], and that [Text][Text Property] is the same as was initially provided. + +Please note that these examples all perform a search which has at most one valid match in the text. + +#### SearchOptions.LiteralText + +These examples find and replace all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | + +#### SearchOptions.PatternMatching + +These examples find and replace all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `"*"` | `"ReplacementText"` | +| `"The"` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"*"` | `"ReplacementText"` | +| `"The"` | `"*"` | `""` | `"ReplacementText"` | +| `"The"` | `""` | `"*"` | `"ReplacementText"` | +| `"*"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"*"` | `"ReplacementText"` | +| `"*"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `""` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"*"` | `"ReplacementText"` | +| `"*"` | `"*"` | `""` | `"ReplacementText"` | +| `"*"` | `""` | `"*"` | `"ReplacementText"` | +| `"*"` | `""` | `""` | `"ReplacementText"` | +| `""` | `"quick"` | `"*"` | `"The ReplacementText"` | +| `""` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `""` | `"*"` | `"*"` | `"ReplacementText"` | +| `""` | `"*"` | `""` | `"ReplacementText"` | +| `""` | `""` | `"*"` | `"ReplacementText"` | + +#### SearchOptions.Regex + +These examples find and replace all occurrences in [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `".*"` | `"ReplacementText"` | +| `"The"` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `".*"` | `"ReplacementText"` | +| `"The"` | `".*"` | `""` | `"ReplacementText"` | +| `"The"` | `""` | `".*"` | `"ReplacementText"` | +| `".*"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `".*"` | `"ReplacementText"` | +| `".*"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `""` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `".*"` | `"ReplacementText"` | +| `".*"` | `".*"` | `""` | `"ReplacementText"` | +| `".*"` | `""` | `".*"` | `"ReplacementText"` | +| `".*"` | `""` | `""` | `"ReplacementText"` | +| `""` | `"quick"` | `".*"` | `"The ReplacementText"` | +| `""` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `""` | `".*"` | `".*"` | `"ReplacementText"` | +| `""` | `".*"` | `""` | `"ReplacementText"` | +| `""` | `""` | `".*"` | `"ReplacementText"` | + +### 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 Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), or [Text To Find][TextToFind Property] is `null`; no operation is performed and the [Text][Text Property] remains unchanged. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not considered as part of the matches for [Text to Find][TextToFind Property] when determining what to replace; see [Advanced Examples][]. + +### Null or empty Replacement Text + +If [Replacement Text][ReplacementText Property] is `null` or empty (i.e. `""`) all occurrences of [Text To Find][TextToFind Property] are replaced with an empty text (i.e. `""`). + +### Text To Find is not present + +If [Text To Find][TextToFind 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 Find][TextToFind Property] replaced and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[ReplacementText Property]: {{< ref "#replacement-text" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} + +[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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md new file mode 100644 index 000000000..74cde5de1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-and-replace-text/find-and-replace-text-block.md @@ -0,0 +1,416 @@ +--- +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/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceTextBlock.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 Find][TextToFind 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 LiteralText, PatternMatching or Regex search to find the [Text To Find][TextToFind Property]. + +## Examples + +### Replace the first Occurrence of text + +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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [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.LiteralText` | `($)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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Text` will be updated to `"a quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Replace the second Occurrence of text + +This example will find and replace the second 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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText` with value `"a"`| `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `2` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence `"the"`. Therefore, the variable `($)Text` will be updated to `"The quick brown fox jumps over a lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Replace the last Occurrence of text + +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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [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.LiteralText` | `($)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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence `"the"`. The second occurrence is also the last occurrence, and therefore, the variable `($)Text` will be updated to `"The quick brown fox jumps over a lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Replace an invalid Occurrence of text + +This example will find and replace the third occurrence of `"The"`, which is not present, 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 Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Replacement Text][ReplacementText Property] | `($)ReplacementText` with value `"a"`| `($)ReplacementText` is a variable of type [String][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `3` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)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 the text (`"The quick brown fox jumps over the lazy dog."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. There is no match for the third occurrence. Therefore, the variable `($)Text` will be not be updated and remains as `"The quick brown fox jumps over the lazy dog."`. + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find and replace the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query used to find and replace the specified matching occurrence in [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Replacement Text + +The [Replacement Text][ReplacementText Property] used to replace the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind 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 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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +## 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 the execution time of any search done to find the specific occurrence of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Occurrence][Occurrence Property] | `1` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | +| [Replacement Text][ReplacementText Property] | `"ReplacementText"` | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Output Text | The value of the [Text][Text Property] after executing the block. \* | +\* *DEFAULT* indicates that nothing has been found and replaced in [Text][Text Property], and that [Text][Text Property] is the same as was initially provided. + +Please note that these examples all perform a search which has at most one valid match in the text. + +#### SearchOptions.LiteralText + +These examples find and replace the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | + +#### SearchOptions.PatternMatching + +These examples find and replace the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `"*"` | `"ReplacementText"` | +| `"The"` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"*"` | `"ReplacementText"` | +| `"The"` | `"*"` | `""` | `"ReplacementText"` | +| `"The"` | `""` | `"*"` | `"ReplacementText"` | +| `"*"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"*"` | `"ReplacementText"` | +| `"*"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `""` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"*"` | `"*"` | `"*"` | `"ReplacementText"` | +| `"*"` | `"*"` | `""` | `"ReplacementText"` | +| `"*"` | `""` | `"*"` | `"ReplacementText"` | +| `"*"` | `""` | `""` | `"ReplacementText"` | +| `""` | `"quick"` | `"*"` | `"The ReplacementText"` | +| `""` | `"*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `""` | `"*"` | `"*"` | `"ReplacementText"` | +| `""` | `"*"` | `""` | `"ReplacementText"` | +| `""` | `""` | `"*"` | `"ReplacementText"` | + +#### SearchOptions.Regex + +These examples find and replace the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Output Text | +|-----------------------|---------------------|---------------------|-------------| +| `"The"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `"The"` | `""` | `"brown"` | *DEFAULT* | +| `"The"` | `""` | `""` | `"ReplacementText quick brown fox jumps over the lazy dog."` | +| `""` | `"quick"` | `"brown"` | `"The ReplacementText fox jumps over the lazy dog."` | +| `""` | `"quick"` | `""` | `"The ReplacementText brown fox jumps over the lazy dog."` | +| `""` | `""` | `"brown"` | `"The quick ReplacementText fox jumps over the lazy dog."` | +| `""` | `""` | `""` | *DEFAULT* | +| `"The"` | `"quick"` | `".*"` | `"ReplacementText"` | +| `"The"` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `".*"` | `"ReplacementText"` | +| `"The"` | `".*"` | `""` | `"ReplacementText"` | +| `"The"` | `""` | `".*"` | `"ReplacementText"` | +| `".*"` | `"quick"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `".*"` | `"ReplacementText"` | +| `".*"` | `"quick"` | `""` | `"ReplacementText brown fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `""` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `".*"` | `".*"` | `".*"` | `"ReplacementText"` | +| `".*"` | `".*"` | `""` | `"ReplacementText"` | +| `".*"` | `""` | `".*"` | `"ReplacementText"` | +| `".*"` | `""` | `""` | `"ReplacementText"` | +| `""` | `"quick"` | `".*"` | `"The ReplacementText"` | +| `""` | `".*"` | `"brown"` | `"ReplacementText fox jumps over the lazy dog."` | +| `""` | `".*"` | `".*"` | `"ReplacementText"` | +| `""` | `".*"` | `""` | `"ReplacementText"` | +| `""` | `""` | `".*"` | `"ReplacementText"` | + +### 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 Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), or [Text To Find][TextToFind Property] is `null`; no operation is performed and the [Text][Text Property] remains unchanged. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not considered as part of the matches for [Text to Find][TextToFind Property] when determining what to replace; see [Advanced Examples][]. + +### Null or empty Replacement Text + +If [Replacement Text][ReplacementText Property] is `null` or empty (i.e. `""`) all occurrences of [Text To Find][TextToFind Property] are replaced with an empty text (i.e. `""`). + +### Text To Find is not present + +If [Text To Find][TextToFind 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 Find][TextToFind Property] replaced and re-assigns it to the variable specified in the [Text][Text Property] property. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[Text Property]: {{}} +[TextToFind Property]: {{}} +[ReplacementText Property]: {{}} +[Occurrence Property]: {{}} +[SearchOptions Property]: {{}} +[ComparisonType Property]: {{}} + +[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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/_index.md new file mode 100644 index 000000000..e04585aac --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Find Text" +linkTitle: "Find Text" +description: "Find text in another text" +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-all-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-all-text-block.md new file mode 100644 index 000000000..65d013756 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-all-text-block.md @@ -0,0 +1,470 @@ +--- +title: "Find All Text" +linkTitle: "Find All Text" +description: "Finds all occurrences of a text in a given text." +--- +{{< figure src="/blocks/Cortex_Blocks_Text_FindText_FindAllTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindText.FindAllTextBlock)

+ +## Description + +Finds all occurrences of [Text To Find][TextToFind Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a LiteralText, PatternMatching or Regex search to match the [Text To Find][TextToFind Property] input. + +## Examples + +### Find all occurrences when there are multiple matches + +This example will find 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [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 [List][]<[Match][]> 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."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Matches` will be updated to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + }, + { + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } + } +] +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Find all occurrences when there is a single match + +This example will find 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [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 [List][]<[Match][]> 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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Matches` will be set to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + } +] +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Find all occurrences when there are no matches + +This example will find all occurrences of `"cat"` 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 `{"startsWith": "", "contains": "cat", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "cat", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [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 [List][]<[Match][]> value | + +#### Results + +`"The quick brown fox jumps over the lazy dog."` does not contain an occurrence of `"cat"`. Therefore, `($)Matches` will be set to the following: + +```json +[] +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find all occurrences of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| 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] search query used to find all matching occurrences in [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +### Matches + +The [List][]<[Match][]> containing all valid matches found for the [Text To Find][TextToFind Property] search query. + +| | | +|--------------------|---------------------------| +| Data Type | [List][]<[Match][]> | +| 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 [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 the execution time of any search done to find all occurrences of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | +| [Matches][Matches Property] | `($)Matches` with no value | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Matches[0].Value | The Value property of the first match of the [Matches][Matches Property] returned. \* | +| Matches[0].Groups["startsWith"].Value | The value of the "startsWith" Group within the first match of the [Matches][Matches Property]. \* | +| Matches[0].Groups["contains"].Value | The value of the "contains" Group within the first match of the [Matches][Matches Property]. \* | +| Matches[0].Groups["endsWith"].Value | The value of the "endsWith" Group within the first match of the [Matches][Matches Property]. \* | + +\* *No Match* indicates that no match was found and *N/A* indicates that the group is not returned as part of the [Matches][Matches Property]. + +Please note that these examples all perform a search which has at most one valid match in the text. + +#### SearchOptions.LiteralText + +These examples find the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Matches[0].Value | Matches[0].Groups["startsWith"].Value | Matches[0].Groups["contains"].Value | Matches[0].Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | + +#### SearchOptions.PatternMatching + +These examples find the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Matches[0].Value | Matches[0].Groups["startsWith"].Value | Matches[0].Groups["contains"].Value | Matches[0].Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | +| `"The"` | `"quick"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"brown"` | `"The quick brown"` | `"The"` | `" quick "` | `"brown"` | +| `"The"` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | `""` | +| `"The"` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | *N/A* | +| `"The"` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | *N/A* | `" quick brown fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The "` | `"quick"` | `"brown"` | +| `"*"` | `"quick"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The "` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `""` | `"The quick"` | `"The "` | `"quick"` | *N/A* | +| `"*"` | `"*"` | `"brown"` | `"The quick brown"` | `"The quick "` | `""` | `"brown"` | +| `"*"` | `""` | `"brown"` | `"The quick brown"` | `"The quick "` | *N/A* | `"brown"` | +| `"*"` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | `""` | +| `"*"` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | *N/A* | +| `"*"` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `""` | +| `"*"` | `""` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | +| `""` | `"quick"` | `"*"` | `"quick brown fox jumps over the lazy dog."` | *N/A* | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `""` | `"*"` | `"brown"` | `"The quick brown"` | *N/A* | `"The quick "` | `"brown"` | +| `""` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | `""` | +| `""` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | *N/A* | +| `""` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | `"The quick brown fox jumps over the lazy dog."` | + +#### SearchOptions.Regex + +These examples find the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex` using a [case-sensitive, culture-insensitive][Ordinal] search. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Matches[0].Value | Matches[0].Groups["startsWith"].Value | Matches[0].Groups["contains"].Value | Matches[0].Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | +| `"The"` | `"quick"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `"brown"` | `"The quick brown"` | `"The"` | `" quick "` | `"brown"` | +| `"The"` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | `""` | +| `"The"` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | *N/A* | +| `"The"` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | *N/A* | `" quick brown fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The "` | `"quick"` | `"brown"` | +| `".*"` | `"quick"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The "` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `""` | `"The quick"` | `"The "` | `"quick"` | *N/A* | +| `".*"` | `".*"` | `"brown"` | `"The quick brown"` | `"The quick "` | `""` | `"brown"` | +| `".*"` | `""` | `"brown"` | `"The quick brown"` | `"The quick "` | *N/A* | `"brown"` | +| `".*"` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | `""` | +| `".*"` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | *N/A* | +| `".*"` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `""` | +| `".*"` | `""` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | +| `""` | `"quick"` | `".*"` | `"quick brown fox jumps over the lazy dog."` | *N/A* | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `""` | `".*"` | `"brown"` | `"The quick brown"` | *N/A* | `"The quick "` | `"brown"` | +| `""` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | `""` | +| `""` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | *N/A* | +| `""` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | `"The quick brown fox jumps over the lazy dog."` | + +### 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. `""`) no operation is performed and [Matches][Matches Property] is set to an empty [List][]<[Match][]>. + +### Null or empty Text To Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), or [Text To Find][TextToFind Property] is `null`; no operation is performed and [Matches][Matches Property] is set to an empty [List][]<[Match][]>. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not included as a specific [Group][] for any [Match][] within the returned [Matches][Matches Property]; see [Advanced Examples][]. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that are equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Matches Property]: {{< ref "#matches" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} + +[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" >}} + +[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" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.MainDoc" >}} +[Group]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Group.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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-text-block.md new file mode 100644 index 000000000..d9927c071 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/find-text/find-text-block.md @@ -0,0 +1,513 @@ +--- +title: "Find Text" +linkTitle: "Find Text" +description: "Finds the specified occurrence of a text in a given text." +--- +{{< figure src="/blocks/Cortex_Blocks_Text_FindText_FindTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindText.FindTextBlock)

+ +## Description + +Finds the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a LiteralText, PatternMatching or Regex search to match the [Text To Find][TextToFind Property] input. + +## Examples + +### Find the first Occurrence of text + +This example will find the first [occurrence][Occurrence Property] 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to a [Match][] 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."`), the text contains `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } +} +``` + +For more information on using [Search Options][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Find the second Occurrence of text + +This example will find the second [occurrence][Occurrence Property] 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `2` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to a [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of the text (`"The quick brown fox jumps over the lazy dog."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } +} +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Find the last Occurrence of text + +This example will find the last [occurrence][Occurrence Property] 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to a [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of the text (`"The quick brown fox jumps over the lazy dog."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. The second occurrence is also the last occurrence, and therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } +} +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +### Find an invalid Occurrence of text + +This example will find the third [occurrence][Occurrence Property] of `"The"`, which is not present, 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 `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith: "")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `3` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.LiteralText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to a [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of the text (`"The quick brown fox jumps over the lazy dog."`), the text contains `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. There is no match for the third occurrence. Therefore, the variable `($)Match` will be set to the following: + +```json +null +``` + +For more information on using [SearchOptions][SearchOptions Property] and [Text To Find][TextToFind Property] see [Advanced Examples][]. + +*** + +## Properties + +### Text + +The [Text][Text Property] to find the specified occurrence of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| 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] search query used to find the specified matching occurrence in [Text][Text Property]. This property contains the following sub-properties: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +See [Advanced Examples][] for more information on how to use these sub-properties. + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Occurrence + +The [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 LiteralText, PatternMatching or Regex search: + +* `SearchOptions.LiteralText` 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 overlapping matches are not detected (i.e. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` but not `"aa"` at index `1`). + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `LiteralText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [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` | + +### Match + +The [Match][] containing the valid match found for the [Text To Find][TextToFind Property] search query. + +| | | +|--------------------|---------------------------| +| Data Type | [Match][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Match` 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 the execution time of any search done to find the specific occurrence of [Text to Find][TextToFind Property] exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Advanced Examples + +The following sections will show examples for each possible value of [Search Options][SearchOptions Property]. + +In these examples, the following properties are common: + +| Property | Value | +|----------|-------| +| [Text][Text Property] | `"The quick brown fox jumps over the lazy dog."` | +| [Occurrence][Occurrence Property] | `1` | +| [Comparison Type][ComparisonType Property] | `Ordinal` | +| [Match][] | `($)Match` with no value | + +These sections contain tables for the examples. The columns of these tables are explained below: + +| Column Name | Explanation | +|-------------|-------------| +| TextToFind.StartsWith | Value used to define the StartsWith property of [Text To Find][TextToFind Property]. | +| TextToFind.Contains | Value used to define the Contains property of [Text To Find][TextToFind Property]. | +| TextToFind.EndsWith | Value used to define the EndsWith property of [Text To Find][TextToFind Property]. | +| Match.Value | The Value property of the [Match][Match Property] returned. \* | +| Match.Groups["startsWith"].Value | The value of the "startsWith" Group within the [Match][Match Property]. \* | +| Match.Groups["contains"].Value | The value of the "contains" Group within the [Match][Match Property]. \* | +| Match.Groups["endsWith"].Value | The value of the "endsWith" Group within the [Match][Match Property]. \* | + +\* *No Match* indicates that no match was found and *N/A* indicates that the group is not returned as part of the [Match][Match Property]. + +#### SearchOptions.LiteralText + +These examples find and remove the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `LiteralText`. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Match.Value | Match.Groups["startsWith"].Value | Match.Groups["contains"].Value | Match.Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | + +#### SearchOptions.PatternMatching + +These examples find and remove the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `PatternMatching`. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Match.Value | Match.Groups["startsWith"].Value | Match.Groups["contains"].Value | Match.Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | +| `"The"` | `"quick"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `"*"` | `"brown"` | `"The quick brown"` | `"The"` | `" quick "` | `"brown"` | +| `"The"` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | `""` | +| `"The"` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | *N/A* | +| `"The"` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | *N/A* | `" quick brown fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The "` | `"quick"` | `"brown"` | +| `"*"` | `"quick"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The "` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"*"` | `"quick"` | `""` | `"The quick"` | `"The "` | `"quick"` | *N/A* | +| `"*"` | `"*"` | `"brown"` | `"The quick brown"` | `"The quick "` | `""` | `"brown"` | +| `"*"` | `""` | `"brown"` | `"The quick brown"` | `"The quick "` | *N/A* | `"brown"` | +| `"*"` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | `""` | +| `"*"` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | *N/A* | +| `"*"` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `""` | +| `"*"` | `""` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | +| `""` | `"quick"` | `"*"` | `"quick brown fox jumps over the lazy dog."` | *N/A* | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `""` | `"*"` | `"brown"` | `"The quick brown"` | *N/A* | `"The quick "` | `"brown"` | +| `""` | `"*"` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | `""` | +| `""` | `"*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | *N/A* | +| `""` | `""` | `"*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | `"The quick brown fox jumps over the lazy dog."` | + +#### SearchOptions.Regex + +These examples find and remove the first occurrence in [Text][Text Property] with [Search Options][SearchOptions Property] set to `Regex`. + +| TextToFind.StartsWith | TextToFind.Contains | TextToFind.EndsWith | Match.Value | Match.Groups["startsWith"].Value | Match.Groups["contains"].Value | Match.Groups["endsWith"].Value | +|------------|----------|----------|--------------|------------------|----------------|----------------| +| `"The"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The"` | `"quick"` | `"brown"` | +| `"The"` | `"quick"` | `""` | `"The quick"` | `"The"` | `"quick"` | *N/A* | +| `"The"` | `""` | `"brown"` | *No Match* | *No Match* | *N/A* | *No Match* | +| `"The"` | `""` | `""` | `"The"` | `"The"` | *N/A* | *N/A* | +| `""` | `"quick"` | `"brown"` | `"quick brown"` | *N/A* | `"quick"` | `"brown"` | +| `""` | `"quick"` | `""` | `"quick"` | *N/A* | `"quick"` | *N/A* | +| `""` | `""` | `"brown"` | `"brown"` | *N/A* | *N/A* | `"brown"` | +| `""` | `""` | `""` | *No Match* | *N/A* | *N/A* | *N/A* | +| `"The"` | `"quick"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `"The"` | `".*"` | `"brown"` | `"The quick brown"` | `"The"` | `" quick "` | `"brown"` | +| `"The"` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | `""` | +| `"The"` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | `" quick brown fox jumps over the lazy dog."` | *N/A* | +| `"The"` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The"` | *N/A* | `" quick brown fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `"brown"` | `"The quick brown"` | `"The "` | `"quick"` | `"brown"` | +| `".*"` | `"quick"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The "` | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `".*"` | `"quick"` | `""` | `"The quick"` | `"The "` | `"quick"` | *N/A* | +| `".*"` | `".*"` | `"brown"` | `"The quick brown"` | `"The quick "` | `""` | `"brown"` | +| `".*"` | `""` | `"brown"` | `"The quick brown"` | `"The quick "` | *N/A* | `"brown"` | +| `".*"` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | `""` | +| `".*"` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | `""` | *N/A* | +| `".*"` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `""` | +| `".*"` | `""` | `""` | `"The quick brown fox jumps over the lazy dog."` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | +| `""` | `"quick"` | `".*"` | `"quick brown fox jumps over the lazy dog."` | *N/A* | `"quick"` | `" brown fox jumps over the lazy dog."` | +| `""` | `".*"` | `"brown"` | `"The quick brown"` | *N/A* | `"The quick "` | `"brown"` | +| `""` | `".*"` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | `""` | +| `""` | `".*"` | `""` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | `"The quick brown fox jumps over the lazy dog."` | *N/A* | +| `""` | `""` | `".*"` | `"The quick brown fox jumps over the lazy dog."` | *N/A* | *N/A* | `"The quick brown fox jumps over the lazy dog."` | + +### 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. `""`) no operation is performed and [Match][Match Property] is set to `null`. + +### Null or empty Text To Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`) no operation is performed and [Match][Match Property] is set to `null`. + +### Null or empty property of Text To Find + +If a property of [Text To Find][TextToFind Property] is `null` or empty (i.e. `""`), then it is not included as a specified [Group][] in the returned [Match][Match Property]; see [Advanced Examples][]. + +### Known Limitations + +If [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Advanced Examples]: {{}} +[Match Property]: {{< ref "#match" >}} +[Occurrence Property]:{{}} +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[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" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[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" >}} + +[Group]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Group.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.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" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[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" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/format-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/format-text/_index.md new file mode 100644 index 000000000..3510eb0bb --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/format-text/format-text-with-value-block-1.md b/content/en/docs/2024.9/Reference/Blocks/Text/format-text/format-text-with-value-block-1.md new file mode 100644 index 000000000..ef3e20562 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_FormatText_FormatTextWithValueBlock_1.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/2024.9/Reference/Blocks/Text/format-text/format-text-with-values-block-1.md b/content/en/docs/2024.9/Reference/Blocks/Text/format-text/format-text-with-values-block-1.md new file mode 100644 index 000000000..1fe075c97 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_FormatText_FormatTextWithValuesBlock_1.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() {0, "1"}` | + +### 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 format parameters in [Format Template][FormatTemplate Property] with corresponding [Values][Values 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 less than zero (e.g. `"Hello {-1}"`) or greater than the count of [Values][Values Property] - `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][]). | +| [PropertyNullException][] | Thrown when [Values][Values 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 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]. + +### 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" >}} +[Values Property]: {{< ref "#values" >}} +[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" >}} + +[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" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[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/2024.9/Reference/Blocks/Text/get-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/_index.md new file mode 100644 index 000000000..c3a9c2e87 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Get Text" +linkTitle: "Get Text" +description: "Get text from a given text." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-at-beginning-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-at-beginning-block.md new file mode 100644 index 000000000..197e0541f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-at-beginning-block.md @@ -0,0 +1,114 @@ +--- +title: "Get Text At Beginning" +linkTitle: "Get Text At Beginning" +description: "Gets a length of text from the beginning of a given text." +--- + +{{< figure src="/blocks/Cortex_Blocks_Text_GetText_GetTextAtBeginningBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/Text/get-text/get-text-at-end-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-at-end-block.md new file mode 100644 index 000000000..4f822d37c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetText_GetTextAtEndBlock.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/2024.9/Reference/Blocks/Text/get-text/get-text-at-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-at-index-block.md new file mode 100644 index 000000000..b4a4b80cb --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetText_GetTextAtIndexBlock.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/2024.9/Reference/Blocks/Text/get-text/get-text-before-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-before-index-block.md new file mode 100644 index 000000000..ec7e18142 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetText_GetTextBeforeIndexBlock.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/2024.9/Reference/Blocks/Text/get-text/get-text-between-indexes-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/get-text/get-text-between-indexes-block.md new file mode 100644 index 000000000..30d78b689 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_GetText_GetTextBetweenIndexesBlock.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/2024.9/Reference/Blocks/Text/is-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/_index.md new file mode 100644 index 000000000..1b1f9d50d --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/is-text/is-text-empty-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-empty-block.md new file mode 100644 index 000000000..35898d82e --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextEmptyBlock.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/2024.9/Reference/Blocks/Text/is-text/is-text-empty-or-whitespace-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-empty-or-whitespace-block.md new file mode 100644 index 000000000..0e23dcfa8 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextEmptyOrWhitespaceBlock.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/2024.9/Reference/Blocks/Text/is-text/is-text-equal-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-equal-block.md new file mode 100644 index 000000000..9474ebb9f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextEqualBlock.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/2024.9/Reference/Blocks/Text/is-text/is-text-null-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-null-block.md new file mode 100644 index 000000000..f4a7bb7dc --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextNullBlock.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/2024.9/Reference/Blocks/Text/is-text/is-text-null-empty-or-whitespace-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-null-empty-or-whitespace-block.md new file mode 100644 index 000000000..e53183a46 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextNullEmptyOrWhitespaceBlock.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/2024.9/Reference/Blocks/Text/is-text/is-text-null-or-empty-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/is-text/is-text-null-or-empty-block.md new file mode 100644 index 000000000..2228fbcfe --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_IsText_IsTextNullOrEmptyBlock.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/2024.9/Reference/Blocks/Text/join-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/join-text/_index.md new file mode 100644 index 000000000..60c7d1193 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/join-text/join-text-block-1.md b/content/en/docs/2024.9/Reference/Blocks/Text/join-text/join-text-block-1.md new file mode 100644 index 000000000..8296d6f30 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_JoinText_JoinTextBlock_1.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/2024.9/Reference/Blocks/Text/remove-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/_index.md new file mode 100644 index 000000000..73ba8925c --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-beginning-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-beginning-block.md new file mode 100644 index 000000000..faad3bab9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_RemoveText_RemoveTextAtBeginningBlock.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/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-end-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-end-block.md new file mode 100644 index 000000000..932ea0f2a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_RemoveText_RemoveTextAtEndBlock.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/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/remove-text-at-index-block.md new file mode 100644 index 000000000..49b78c595 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_RemoveText_RemoveTextAtIndexBlock.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/2024.9/Reference/Blocks/Text/remove-text/remove-text-before-index-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/remove-text-before-index-block.md new file mode 100644 index 000000000..d91eb1419 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_RemoveText_RemoveTextBeforeIndexBlock.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/2024.9/Reference/Blocks/Text/remove-text/remove-text-between-indexes-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/remove-text/remove-text-between-indexes-block.md new file mode 100644 index 000000000..afde04054 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_RemoveText_RemoveTextBetweenIndexesBlock.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/2024.9/Reference/Blocks/Text/split-text/_index.md b/content/en/docs/2024.9/Reference/Blocks/Text/split-text/_index.md new file mode 100644 index 000000000..498cf5969 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/Text/split-text/split-text-block.md b/content/en/docs/2024.9/Reference/Blocks/Text/split-text/split-text-block.md new file mode 100644 index 000000000..adbff686e --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Text_SplitText_SplitTextBlock.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/2024.9/Reference/Blocks/_index.md b/content/en/docs/2024.9/Reference/Blocks/_index.md new file mode 100644 index 000000000..321f178f6 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/data-storage/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/_index.md new file mode 100644 index 000000000..1ec60a4e9 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/data-storage/create-collection/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/create-collection/_index.md new file mode 100644 index 000000000..7d76634a0 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md new file mode 100644 index 000000000..b3246083b --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/create-collection/create-collection-block.md @@ -0,0 +1,139 @@ +--- +title: "Create Collection" +linkTitle: "Create Collection" +description: "Create a data storage collection." +--- +{{
}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +This creates a new [Data Storage Collection] within the [Collection Scope][Collection Scope Property] with [Collection Name][Collection Name Property] `"users"`. + +### Create a Data Storage Collection that Already Exists + +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]. +In this example `"users"` already exists. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Attempting to create a [Data Storage Collection] with the name `"users"` within the [Collection Scope][Collection Scope Property] results in no operation, as the [Data Storage Collection] already exists. + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] to create the [Data Storage Collection] within. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with the value shown below: | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection] to create. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| [ServiceDoesNotExistException][] | Thrown when the [Data Storage Service][] does not exist. | +| [ServiceUnavailableException][] | Thrown when the [Data Storage Service][] is not healthy. | + +## Remarks + +### Creating a Collection that Already Exists + +When trying to create a collection that already exists, no operation is performed; see example [Create a Data Storage Collection that Already Exists][Collection Already Exists]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. 'Collection' is the same as 'collection'), so trying to create a [Data Storage Collection] named `"Collection"` while `"COLLECTION"` already exists would have no effect; see example [Create a Data Storage Collection that Already Exists][Collection Already Exists]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Collection Already Exists]: {{< ref "#create-a-data-storage-collection-that-already-exists">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ServiceDoesNotExistException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceDoesNotExistException.MainDoc">}} +[ServiceUnavailableException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceUnavailableException.MainDoc">}} +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.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" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.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/2024.9/Reference/Blocks/data-storage/delete-collection/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-collection/_index.md new file mode 100644 index 000000000..55e7c9294 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-collection/_index.md @@ -0,0 +1,5 @@ +--- +title: "Delete Collection" +linkTitle: "Delete Collection" +description: "Delete a data storage collection." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-collection/delete-collection-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-collection/delete-collection-block.md new file mode 100644 index 000000000..d22a27e01 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-collection/delete-collection-block.md @@ -0,0 +1,147 @@ +--- +title: "Delete Collection" +linkTitle: "Delete Collection" +description: "Deletes a data storage collection." +--- + +{{
}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +This deletes the [Data Storage Collection] within the [Collection Scope][Collection Scope Property] with [Collection Name][Collection Name Property] `"users"`. + +*** + +### Delete a Data Storage Collection that Does Not Exist + +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"` does not exist. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Attempting to delete a [Data Storage Collection] with the name `"users"` within the [Collection Scope][Collection Scope Property] results in no operation, as the [Data Storage Collection] does not exist. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] to delete the [Data Storage Collection] from. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value show below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection] to delete. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| [ServiceDoesNotExistException][] | Thrown when the [Data Storage Service][] does not exist. | +| [ServiceUnavailableException][] | Thrown when the [Data Storage Service][] is not healthy. | + +## Remarks + +### Deleting a Collection that Does Not Exist + +When trying to delete a collection that does not exist, no operation is performed; see example [Delete a Data Storage Collection that Does Not Exist][Delete Collection that Does Not Exist]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. 'Collection' is the same as 'collection'), so trying to delete a [Data Storage Collection] named `"Collection"` while `"COLLECTION"` exists would delete `"COLLECTION"`; see example [Delete a Data Storage Collection][Delete Collection]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} + +[Delete Collection]: {{< ref "#delete-a-data-storage-collection">}} +[Delete Collection that Does Not Exist]: {{< ref "#delete-a-data-storage-collection-that-does-not-exist" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ServiceDoesNotExistException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceDoesNotExistException.MainDoc">}} +[ServiceUnavailableException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceUnavailableException.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.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" >}} +[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/2024.9/Reference/Blocks/data-storage/delete-data/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-data/_index.md new file mode 100644 index 000000000..aa6ec59f5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-data/_index.md @@ -0,0 +1,5 @@ +--- +title: "Delete Data" +linkTitle: "Delete Data" +description: "Delete data from a data storage collection." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-data/delete-data-with-key-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-data/delete-data-with-key-block.md new file mode 100644 index 000000000..ec7973ff9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/delete-data/delete-data-with-key-block.md @@ -0,0 +1,189 @@ +--- +title: "Delete Data With Key" +linkTitle: "Delete Data With Key" +description: "Deletes data from a data storage collection with the specified key." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_DeleteData_DeleteDataWithKeyBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | + +#### Result + +This deletes `"user2"` from the [Data Storage Collection][] which removes the data `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` from the `"users"` [Data Storage Collection][] as shown below: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | + +*** + +### Delete from a Data Storage Collection with a Key that Does Not Exist + +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 attempt to delete the [Key][Key Property] `"user3"` and any associated data. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user3"` | `($)Key` is a variable of type [String][] | + +#### Result + +Attempting to delete `"user3"` from the [Data Storage Collection][] `"users"` within the [Collection Scope][Collection Scope Property] results in no operation, as the [Key][Key Property] does not exist. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection] to delete from. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] to delete from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] the data to delete must have. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [DataStorageCollectionNotFoundException][] | Thrown when the [Collection Name][Collection Name Property] can not be found within the specified [Collection Scope][Collection Scope property]. +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null`. | +| [ServiceDoesNotExistException][] | Thrown when the [Data Storage Service][] does not exist. | +| [ServiceUnavailableException][] | Thrown when the [Data Storage Service][] is not healthy. | + +## Remarks + +### Deleting from a Collection with a Key that Does Not Exist +When trying to delete from a collection with a [Key][Key Property] that does not exist, no operation is performed; see example [Delete from a Data Storage Collection with a Key that Does Not Exist][Delete Missing Key]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. 'Collection' is the same as 'collection'), so trying to delete from a [Data Storage Collection] named `"Collection"` while `"COLLECTION"` already exists would delete from `"COLLECTION"`. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Data Property]: {{< ref "#data" >}} +[Delete Missing Key]: {{< ref "#delete-from-a-data-storage-collection-with-a-key-that-does-not-exist">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ServiceDoesNotExistException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceDoesNotExistException.MainDoc">}} +[ServiceUnavailableException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceUnavailableException.MainDoc">}} +[DataStorageCollectionNotFoundException]: {{< url path = "Cortex.Reference.Exceptions.DataStorage.DataStorageCollectionNotFoundException.MainDoc">}} +[KeyInDataStorageCollectionNotFoundException]: {{< url path = "Cortex.Reference.Exceptions.DataStorage.KeyInDataStorageCollectionNotFoundException.MainDoc">}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/_index.md new file mode 100644 index 000000000..5e5187a84 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/_index.md @@ -0,0 +1,5 @@ +--- +title: "Read Data" +linkTitle: "Read Data" +description: "Read data from a data storage collection." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/read-data-with-key-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/read-data-with-key-block.md new file mode 100644 index 000000000..74007abac --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/read-data/read-data-with-key-block.md @@ -0,0 +1,175 @@ +--- +title: "Read Data With Key" +linkTitle: "Read Data With Key" +description: "Reads data from a data storage collection with the specified key." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_ReadData_ReadDataWithKeyBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | +| [Data][Data Property] | `($)Data`, with no value | `($)Data` is a variable that will be of type [dynamic][] | + +#### Result + +This reads `"user2"` from the [Data Storage Collection][] `"users"` which results in the variable `($)Data` being updated to the following: + +```json +{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"} +``` + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection] to read from. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] to read from. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] the [Data][Data Property] to read must have. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +### Data + +The [Data][Data Property] that is read from the [Data Storage Collection] with the matching [Key][Key Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Data` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [DataStorageCollectionNotFoundException][] | Thrown when the [Collection Name][Collection Name Property] can not be found within the specified [Collection Scope][Collection Scope property]. +| [KeyInDataStorageCollectionNotFoundException][] | Thrown when the given [Key][Key Property] can not be found in the [Data Storage Collection] within the specified [Collection Scope][Collection Scope Property]. | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null`. | +| [ServiceDoesNotExistException][] | Thrown when the [Data Storage Service][] does not exist. | +| [ServiceUnavailableException][] | Thrown when the [Data Storage Service][] is not healthy. | + +## Remarks + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. 'Collection' is the same as 'collection'), so trying to read from a [Data Storage Collection] named `"Collection"` while `"COLLECTION"` already exists would read from `"COLLECTION"`. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Data Property]: {{< ref "#data" >}} +[Write Existing Key]: {{< ref "#write-to-a-data-storage-collection-with-a-key-that-already-exists">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ServiceDoesNotExistException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceDoesNotExistException.MainDoc">}} +[ServiceUnavailableException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceUnavailableException.MainDoc">}} +[DataStorageCollectionNotFoundException]: {{< url path = "Cortex.Reference.Exceptions.DataStorage.DataStorageCollectionNotFoundException.MainDoc">}} +[KeyInDataStorageCollectionNotFoundException]: {{< url path = "Cortex.Reference.Exceptions.DataStorage.KeyInDataStorageCollectionNotFoundException.MainDoc">}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/_index.md new file mode 100644 index 000000000..597640892 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wait For Collection" +linkTitle: "Wait For Collection" +description: "Waits for a data storage collection to exist or not exist." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-exist-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-exist-block.md new file mode 100644 index 000000000..8bc5e7a2a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-exist-block.md @@ -0,0 +1,149 @@ +--- +title: "Wait For Collection To Exist" +linkTitle: "Wait For Collection To Exist" +description: "Waits for a data storage collection to exist." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToExistBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Waiting for the `"users"` [Data Storage Collection][] to exist results in the execution waiting until the desired [Collection][Collection Name Property] exists; see [Create Collection][]. + +### Wait for a Data Storage Collection that already exists 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"` 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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Waiting for the `"users"` [Data Storage Collection][] to exist results in the execution progressing as the collection `"users"` already exists. + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] to wait for the [Data Storage Collection][] to exist in. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so trying to wait for a [Data Storage Collection][] named `"Collection"` to exist while `"COLLECTION"` already exists would cause the execution to progress; see [Wait for a Data Storage Collection that already exists to exist][Collection Already Exists]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Collection Already Exists]: {{< ref +"#wait-for-a-data-storage-collection-that-already-exists-to-exist" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-not-exist-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-not-exist-block.md new file mode 100644 index 000000000..324a1f416 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-collection/wait-for-collection-to-not-exist-block.md @@ -0,0 +1,154 @@ +--- +title: "Wait For Collection To Not Exist" +linkTitle: "Wait For Collection To Not Exist" +description: "Waits for a data storage collection to not exist." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToNotExistBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Waiting for the `"users"` [Data Storage Collection][] to not exist results in the execution waiting until the desired [Collection][Collection Name Property] does not exist; see [Delete Collection][Deleted]. + +*** + +### Wait for a Data Storage Collection to not exist when it does not already 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"` does not already exist. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | + +#### Result + +Waiting for the `"users"` [Data Storage Collection][] to not exist results in the execution progressing as the collection `"users"` does not exist. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] to wait for the [Data Storage Collection][] to not exist in. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value| + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} +``` + +### Collection Name + +The name of the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so waiting for a [Data Storage Collection] named `"Collection"` to not exist while `"COLLECTION"` exists will cause the execution to wait; see [Wait for a Data Storage Collection to not exist][Wait For Collection To Not Exist]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Data Property]: {{< ref "#data" >}} +[Wait For Collection To Not Exist]: {{< ref "#wait-for-a-data-storage-collection-to-not-exist" >}} +[Wait For Missing Key]: {{< ref "#wait-for-a-key-to-exist-in-a-data-storage-collection">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[Deleted]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/_index.md new file mode 100644 index 000000000..b69826477 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wait For Key In Collection" +linkTitle: "Wait For Key In Collection" +description: "Wait for changes to a key in a data storage collection." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-be-set-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-be-set-block.md new file mode 100644 index 000000000..3dbb217fe --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-be-set-block.md @@ -0,0 +1,227 @@ +--- +title: "Wait For Key In Collection To Be Set" +linkTitle: "Wait For Key In Collection To Be Set" +description: "Waits for a key in a collection to be set." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToBeSetBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user1"` | `($)Key` is a variable of type [String][] | +| [Old Value][Old Value Property] | `($)OldValue`, with no value | `($)OldValue` is a variable of type [dynamic][] | +| [New Value][New Value Property] | `($)NewValue`, with no value | `($)NewValue` is a variable of type [dynamic][] | + +#### Result + +Waiting for `"user1"` to be set in the [Data Storage Collection][] results in the execution waiting until the [Key][Key Property] `"user1"` is updated to have any value; see [Write Data With Key][Write Data With Key]. +On the update to the value of `"user1"`, [Old Value][Old Value Property] will have the value `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}`. [New Value][New Value Property] will have the value `{"Domain": "newDomain", "Username": "newUser1", "Password": "encryptedPassword"}`. + +*** + +### Wait for a Key to be set in a Data Storage Collection where the Key does not already exist + +This example will wait for a [Key][Key Property] `"user3"` 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 add the following key and data: +|Key | Data | +-------------|--------------| +|`"user3"` | `{"Domain": "domain", "Username": "user3", "Password": "encryptedPassword"}` | + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Collection Scope][Collection Scope Property] | `($)Scope` with value `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user3"` | `($)Key` is a variable of type [String][] | +| [Old Value][Old Value Property] | `($)OldValue`, with no value | `($)OldValue` is a variable of type [dynamic][] | +| [New Value][New Value Property] | `($)NewValue`, with no value | `($)NewValue` is a variable of type [dynamic][] | + +#### Result + +Waiting for `"user3"` to be set in the [Data Storage Collection][] results in the execution waiting until the [Key][Key Property] `"user3"` is created; see [Write Data With Key][Write Data With Key]. +On the creation of `"user3"` [Old Value][Old Value Property] will have the value `null`, as the key did not exist before being set to a value. +[New Value][New Value Property] will have the value `{"Domain": "domain", "Username": "user3", "Password": "encryptedPassword"}`. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value show below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] containing the [Key][Key Property] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] to wait for. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +### Old Value + +The [Old Value][Old Value Property] associated with the key in the [Data Storage Collection][], i.e. before setting a value. +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)OldValue` with no value | + +### New Value + +The [New Value][New Value Property] associated with the key in the [Data Storage Collection][], i.e. after setting a value. [New Value][New Value Property] can have the same value as [Old Value][Old Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)NewValue` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null` | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so waiting for a [Key][Key Property] `"key"` to be set in a [Data Storage Collection][] named `"Collection"` while `"COLLECTION"` already contains a key `"key"` will cause the execution to progress if the [Key][Key Property] `"key"` in the [Collection Scope][Collection Scope Property] is set. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +### Waiting for a Key to Be Set in a Collection That Does Not Exist + +Waiting for a key to be set, in a collection that doesn't exist, it is treated the same as when waiting for a key that does not exist to be set; see [Wait for a Key to be set in a Data Storage Collection where the Key does not already exist][Wait For Missing Key]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Data Property]: {{< ref "#data" >}} +[Wait For Missing Key]: {{< ref +"#wait-for-a-key-to-be-set-in-a-data-storage-collection-where-the-key-does-not-already-exist">}} +[Old Value Property]: {{< ref "#old-value" >}} +[New Value Property]: {{< ref "#new-value" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} +[Write Data With Key]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc" >}} +[Delete Collection]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-contain-value-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-contain-value-block.md new file mode 100644 index 000000000..298f37e0e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-contain-value-block.md @@ -0,0 +1,198 @@ +--- +title: "Wait For Key In Collection To Contain Value" +linkTitle: "Wait For Key In Collection To Contain Value" +description: "Waits for a key in a collection to contain the specified value." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToContainValueBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | +| [Value][Value Property] | `($)Value` with value `{"Domain": "domain", "Username": "admin", "Password": "encryptedPassword"}`.

In this example `($)Value` has been set up using the following [Expression][]:

`new UserCredentials(domain: "domain", username: "admin", password: "encryptedPassword")` | `($)Value` is a variable of type [UserCredentials][] | + +#### Result + +Waiting for `"user2"` to contain [Value][Value Property] `{"Domain": "domain", "Username": "admin", "Password": "encryptedPassword"}` in the [Data Storage Collection][] results in the execution waiting until the the key `"user2"` contains the desired [Value][Value Property]; see [Write Data With Key][Write Data With Key]. + +*** + +### Wait for a Key in a Data Storage Collection to contain Value which it already contains + +This example will wait for a [Key][Key Property] `"user2"` to contain the [Value][Value Property] `{"Domain": "domain", "Username": "user2", "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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | +| [Value][Value Property] | `($)Value` with value `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}`.

In this example `($)Value` has been set up using the following [Expression][]:

`new UserCredentials(domain: "domain", username: "user2", password: "encryptedPassword")` | `($)Value` is a variable of type [UserCredentials][] | + +#### Result + +Waiting for `"user2"` to contain `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` in the [Data Storage Collection][] results in the execution progressing as the key `"user2"` already contains the desired [Value][Value Property]. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] containing the [Key][Key Property] and [Value][Value Property] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] containing the [Value][Value Property] to match. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +### Value + +The [Value][Value Property] to match. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Value` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null`. | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so waiting for a [Key][Key Property] `"key"` in a [Data Storage Collection][] named `"Collection"` to contain a [Value][Value Property] while `"COLLECTION"` already contains `"key"` will cause the execution to progress. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +### Waiting For a Key in a Collection That Does Not Exist to Contain a Value + +When trying to wait for a [Key][Key Property] to contain a value and the specified [Data Storage Collection][] does not exist, it is treated the same as when a key does not have a matching value; see [Wait for a Key in a Data Storage Collection to contain Value][Waiting For Key Value When Different]. + +### Waiting For a Key That Does Not Exist in a Collection To Contain a Value + +When trying to wait for a [Key][Key Property] that does not exist, in a collection that does exist, to contain a value, it is treated the same as when a key does not have a matching value; see [Wait for a Key in a Data Storage Collection to contain Value][Waiting For Key Value When Different]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Value Property]: {{< ref "#value" >}} +[Waiting For Key Value When Different]: {{< ref "#wait-for-a-key-in-a-data-storage-collection-to-contain-value">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Write Data With Key]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-exist-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-exist-block.md new file mode 100644 index 000000000..2cbe8f5ba --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-exist-block.md @@ -0,0 +1,182 @@ +--- +title: "Wait For Key In Collection To Exist" +linkTitle: "Wait For Key In Collection To Exist" +description: "Waits for a key in a collection to exist." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToExistBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user3"` | `($)Key` is a variable of type [String][] | + +#### Result + +Waiting for `"user3"` to exist in the [Data Storage Collection][] results in the execution waiting until `"users"` contains the desired [Key][Key Property]; see [Write Data With Key][Write Data With Key]. + +### Wait for a Key to exist in a Data Storage Collection where the Key already exists + +This example will wait for a [Key][Key Property] `"user2"` 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 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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | + +#### Result + +Waiting for `"user2"` to exist in the [Data Storage Collection][] results in the execution progressing as `"users"` already contains the desired [Key][Key Property]. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value show below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] containing the [Key][Key Property] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] to wait for. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null` | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so waiting for a [Key][Key Property] `"key"` to exist in a [Data Storage Collection][] named `"Collection"` while `"COLLECTION"` already contains a key `"key"` will cause the execution to progress. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +### Waiting For a Key to Exist in a Collection That Doesn't Exist + +When trying to wait for a key to exist, in a collection that doesn't exist, it is treated the same as when a key does not exist in a collection that does exist; see [Wait for a Key to exist in a Data Storage Collection][Wait For Missing Key]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Data Property]: {{< ref "#data" >}} +[Wait For Missing Key]: {{< ref +"#wait-for-a-key-to-exist-in-a-data-storage-collection">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} +[Write Data With Key]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} + +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-not-exist-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-not-exist-block.md new file mode 100644 index 000000000..aab4007de --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/wait-for-key-in-collection/wait-for-key-in-collection-to-not-exist-block.md @@ -0,0 +1,177 @@ +--- +title: "Wait For Key In Collection To Not Exist" +linkTitle: "Wait For Key In Collection To Not Exist" +description: "Waits for a key in a collection to not exist." +--- +{{< figure src="/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToNotExistBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | + +#### Result + +Waiting for `"user2"` to not exist in the [Data Storage Collection][] results in the execution waiting until `"users"` does not contain the desired [Key][Key Property]; see [Delete Data With Key][]. + +*** + +### Wait for a Key in a Data Storage Collection to not exist where the Key does not already exist + +This example will wait for a [Key][Key Property] `"user3"` 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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]:

`new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user3"` | `($)Key` is a variable of type [String][] | + +#### Result + +Waiting for `"user3"` to not exist in the [Data Storage Collection][] results in the execution progressing as `"users"` does not contain the desired [Key][Key Property]. + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection][] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] containing the [Key][Key Property] to wait for. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] to wait for. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null`. | + +## Remarks + +### Block Timeout + +This block has a default [Block Timeout][] of 60 seconds. If the execution waits for longer than 60 seconds the block will throw a [BlockTimeoutException][]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. `"Collection"` is the same as `"collection"`), so trying to wait for a key `"key"` to not exist in a [Data Storage Collection][] named `"Collection"` while `"COLLECTION"` already exists would wait for `"key"` to not exist in the [Data Storage Collection][] `"COLLECTION"`. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +### Waiting For a Key in a Collection That Does Not Exist + +When trying to wait for a [Key][Key Property] contained in a collection that does not exist, it is treated the same as when a key does not exist in a collection; see [Wait for a Key in a Data Storage Collection to not exist where the Key does not already exist][Wait For Key To Not Exist]. + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Wait For Key To Not Exist]: {{< ref "#wait-for-a-key-in-a-data-storage-collection-to-not-exist-where-the-key-does-not-already-exist" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} +[Block Timeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Delete Data With Key]: {{< url path = "Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.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" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/_index.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/_index.md new file mode 100644 index 000000000..1d223db89 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/_index.md @@ -0,0 +1,5 @@ +--- +title: "Write Data" +linkTitle: "Write Data" +description: "Write data to a data storage collection." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/write-data-with-key-block.md b/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/write-data-with-key-block.md new file mode 100644 index 000000000..bd7c4c30e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data-storage/write-data/write-data-with-key-block.md @@ -0,0 +1,209 @@ +--- +title: "Write Data With Key" +linkTitle: "Write Data With Key" +description: "Writes data to a data storage collection with the specified key." +--- +{{
}} + +# {{% param title %}} + +

(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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | +| [Data][Data Property] | `($)Data` with value `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}`.

In this example `($)Data` has been set up using the following [Expression][] `new UserCredentials(domain: "domain", username: "user2", password: "encryptedPassword")` | `($)Data` is a variable of type [UserCredentials][] | + +#### Result + +This writes the [Data][Data Property] `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` with the [Key][Key Property] `"user2"` to the [Data Storage Collection][] named `"users"` as shown below: + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +*** + +### Write to a Data Storage Collection with a Key that already exists + +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"}` | +|`"user2"` | `{"Domain": "domain", "Username": "user2", "Password": "encryptedPassword"}` | + +The example will write the [Data][Data Property] `{"Domain": "domain", "Username": "new 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", "Package": "ScopeOption.All", "Flow": "ScopeOption.All"}`.

In this example `($)Scope` has been set up using the following [Expression][]: `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.All, flow: ScopeOption.All)`| `($)Scope` is a variable of type [ScopeDefinition][] | +| [Collection Name][Collection Name Property] | `($)CollectionName` with value `"users"` | `($)CollectionName` is a variable of type [String][] | +| [Key][Key Property] | `($)Key` with value `"user2"` | `($)Key` is a variable of type [String][] | +| [Data][Data Property] | `($)Data` with value `{"Domain": "domain", "Username": "new user2", "Password": "encryptedPassword"}`.

In this example `($)Data` has been set up using the following [Expression][] `new UserCredentials(domain: "domain", username: "new user2", password: "encryptedPassword")` | `($)Data` is a variable of type [UserCredentials][] | + +#### Result + +This example will update the [Data][Data Property] stored to [Key][Key Property] `"user2"` to `{"Domain": "domain", "Username": "new user2", "Password": "encryptedPassword"}` of type [UserCredentials][] in the [Data Storage Collection][] named `"users"` as shown below. + +|Key | Data | +-------------|--------------| +|`"user1"` | `{"Domain": "domain", "Username": "user1", "Password": "encryptedPassword"}` | +|`"user2"` | `{"Domain": "domain", "Username": "new user2", "Password": "encryptedPassword"}` | + +*** + +## Properties + +### Collection Scope + +The [Collection Scope][Collection Scope Property] containing the [Data Storage Collection][] to write to. + +| | | +|--------------------|---------------------------| +| Data Type | [ScopeDefinition] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Collection Scope][Collection Scope Property] with value show below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} + +``` + +### Collection Name + +The name of the [Data Storage Collection][] to write to. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)CollectionName` with no value | + +### Key + +The [Key][Key Property] to add the [Data][Data Property] with. + +The [Key][Key Property] can't be `null` and must be unique within each [Data Storage Collection][]. + +For more information about what a key is, please see [Keys]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Key` with no value | + +### Data + +The [Data][Data Property] to be added to the [Data Storage Collection][] with the specified [Key][Key Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Data` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Tenant][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [System][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Package][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| | Thrown when [Flow][] is not one of the specified [ScopeOption][] types (e.g. `(ScopeOption)100`). | +| [DataStorageCollectionNotFoundException][] | Thrown when the [Collection Name][Collection Name Property] can not be found within the specified [Collection Scope][Collection Scope property]. +| [PropertyEmptyException][] | Thrown when the [Collection Name][Collection Name Property] is empty (i.e. `""`).| +| [PropertyNullException][] | Thrown when the [Collection Scope][Collection Scope Property] is `null`. | +| | Thrown when the [Collection Name][Collection Name Property] is `null`. | +| | Thrown when the [Key][Key Property] is `null` | +| [ServiceDoesNotExistException][] | Thrown when the [Data Storage Service][] does not exist. | +| [ServiceUnavailableException][] | Thrown when the [Data Storage Service][] is not healthy. | + +## Remarks + +### Writing With a Key That Already Exists + +When trying to write to a key that already exists in the [Data Storage Collection][] provided, the value of the key is overwritten; see example [Write to a Data Storage Collection with a Key that Already Exists][Write Existing Key]. + +### Case Sensitivity + +[Collection Name][Collection Name Property] is case insensitive (e.g. 'Collection' is the same as 'collection'), so trying to write to a [Data Storage Collection] named `"Collection"` while `"COLLECTION"` already exists would write to `"COLLECTION"`. + +[Key][Key Property] is case sensitive (e.g. `"user"` is not the same as `"USER"`). + +[Collection Scope Property]: {{< ref "#collection-scope" >}} +[Collection Name Property]: {{< ref "#collection-name" >}} +[Key Property]: {{< ref "#key" >}} +[Data Property]: {{< ref "#data" >}} +[Write Existing Key]: {{< ref "#write-to-a-data-storage-collection-with-a-key-that-already-exists">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant">}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System">}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package">}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow">}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ServiceDoesNotExistException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceDoesNotExistException.MainDoc">}} +[ServiceUnavailableException]: {{< url path = "Cortex.Reference.Exceptions.Services.ServiceUnavailableException.MainDoc">}} +[DataStorageCollectionNotFoundException]: {{< url path = "Cortex.Reference.Exceptions.DataStorage.DataStorageCollectionNotFoundException.MainDoc">}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} +[Data Storage Service]: {{< url path = "Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc">}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/data/_index.md b/content/en/docs/2024.9/Reference/Blocks/data/_index.md new file mode 100644 index 000000000..fb99deffc --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data/_index.md @@ -0,0 +1,5 @@ +--- +title: "Data" +linkTitle: "Data" +description: "Blocks related to working with data sources." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/_index.md b/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/_index.md new file mode 100644 index 000000000..4d20fea6d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute Data Command" +linkTitle: "Execute Data Command" +description: "Blocks related to executing commands against data sources." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md b/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md new file mode 100644 index 000000000..4a8292d48 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/data/execute-data-command/execute-data-command-block-1.md @@ -0,0 +1,806 @@ +--- +title: "Execute Data Command" +linkTitle: "Execute Data Command" +description: "Connects to a specific data source and executes a Command, returning any object from the Command's result." +--- + +{{< figure src="/blocks/Cortex_Blocks_Data_ExecuteDataCommand_ExecuteDataCommandBlock_1.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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}}`

In this example `($)Command` has been set using the following [Expression][]:

`new QueryCommand("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3})` | `($)Command` is a variable of type [QueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Selecting all rows and columns that have an Id less than 3 from `Table` using a [QueryCommand][Command Types QueryCommand] results in the variable `($)Result` being updated to the following: + +```json +[ + { + "Id": 1, + "FirstColumn": "FirstColumn1", + "SecondColumn": "SecondColumn1" + }, + { + "Id": 2, + "FirstColumn": "FirstColumn2", + "SecondColumn": "SecondColumn2" + } +] +``` + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. For an example of a non parameterised command please see [Executing Multiple Commands (Unsafe)][] + +*** + +### Inserting Rows + +This example will insert a new row into a connected SQL Server data source, saving the number of rows inserted to the [Result][Result Property]. + +A [NonQueryCommand][Command Types NonQueryCommand] is used throughout this example to insert data into 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": "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", "Parameters": { "InsertParameter1": \"FirstColumn4\", "InsertParameter2": \"SecondColumn4\" } }`

In this example `($)Command` has been set using the following [Expression][]:

`new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", new { InsertParameter1 = "FirstColumn4", InsertParameter2 = "SecondColumn4" })` | `($)Command` is a variable of type [NonQueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Inserting a new row into `Table` using a parameterised [NonQueryCommand][Command Types NonQueryCommand] results in the variable `($)Result` being updated to the following: + +```json +1 +``` + +This indicates that 1 row has been inserted into `Table`, with `Table` being updated to: + +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `1` | `"FirstColumn1"` | `"SecondColumn1"` | +| `2` | `"FirstColumn2"` | `"SecondColumn2"` | +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | +| `4` | `"FirstColumn4"` | `"SecondColumn4"` | + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. For an example of a non parameterised command please see [Executing Multiple Commands (Unsafe)][] + +*** + +### Updating Rows + +This example will update all rows on a connected SQL Server data source which have an Id less than `3`, saving the number of rows updated to the [Result][Result Property]. + +A [NonQueryCommand][Command Types NonQueryCommand] is used throughout this example to update data in 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": "UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter", "Parameters": { "UpdateParameter": 3 } }`

In this example `($)Command` has been set using the following [Expression][]:

`new NonQueryCommand("UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter", new {UpdateParameter = 3})` | `($)Command` is a variable of type [NonQueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Updating all rows that have an Id less than `3` in `Table` using a [NonQueryCommand][Command Types NonQueryCommand] results in the variable `($)Result` being updated to the following: + +```json +2 +``` + +This indicates that 2 rows have been updated in `Table`, with `Table` being updated to: + +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `1` | `"Updated"` | `"SecondColumn1"` | +| `2` | `"Updated"` | `"SecondColumn2"` | +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. For an example of a non parameterised command please see [Executing Multiple Commands (Unsafe)][] + +*** + +### Deleting Rows + +This example will delete all rows on a connected SQL Server data source which have an Id less than `3`, saving the number of rows deleted to the [Result][Result Property]. + +A [NonQueryCommand][Command Types NonQueryCommand] is used throughout this example to delete data in 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": "DELETE FROM Table WHERE Id < @DeleteParameter", "Parameters": { "DeleteParameter": 3 } }`

In this example `($)Command` has been set using the following [Expression][]:

`new NonQueryCommand("DELETE FROM Table WHERE Id < @DeleteParameter", new {DeleteParameter = 3})` | `($)Command` is a variable of type [NonQueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Deleting all rows that have an Id less than `3` in `Table` using a [NonQueryCommand][Command Types NonQueryCommand] results in the variable `($)Result` being updated to the following: + +```json +2 +``` + +This indicates that 2 rows have been deleted in `Table`, with `Table` being updated to: + +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. For an example of a non parameterised command please see [Executing Multiple Commands (Unsafe)][] + +*** + +### Using Functions + +This example will select the maximum Id value from a connected SQL Server data source, saving the value of the function to the [Result][Result Property]. + +A [QueryCommand][Command Types QueryCommand] is used throughout this example to select the maximum Id value 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 Max(Id) FROM Table", "Parameters": null}`

In this example `($)Command` has been set using the following [Expression][]:

`new QueryCommand("SELECT Max(Id) FROM Table", null)` | `($)Command` is a variable of type [QueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Selecting the maximum Id value from `Table` using a [QueryCommand][Command Types QueryCommand] results in the variable `($)Result` being updated to the following: + +```json +[ + { + "": 3 + } +] +``` + +Note that the `AS` keyword can be used to give aliases to results, for example the CommandText `"SELECT Max(Id) AS MaxId FROM Table;"` would have resulted in the variable `($)Result` being updated to `[ { "MaxId": 3 } ]`; the `AS` keyword also allows for [Using Multiple Functions][]. + +*** + +### Using Multiple Functions + +This example will select the maximum Id value as MaxId and the minimum Id value as MinId from a connected SQL Server data source, saving the values of the functions to the [Result][Result Property]. + +A [QueryCommand][Command Types QueryCommand] is used throughout this example to select the maximum Id value as MaxId and the minimum Id value as MinId 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 Max(Id) AS MaxId, Min(Id) AS MinId FROM Table", "Parameters": null}`

In this example `($)Command` has been set using the following [Expression][]:

`new QueryCommand("SELECT Max(Id) AS MaxId, Min(Id) AS MinId FROM Table", null)` | `($)Command` is a variable of type [QueryCommand][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Selecting the maximum Id value as MaxId and the minimum Id value as MinId from `Table` using a [QueryCommand][Command Types QueryCommand] results in the variable `($)Result` being updated to the following: + +```json +[ + { + "MaxId": 3, + "MinId": 1 + } +] +``` + +*** + +### Executing Multiple Commands (Safe) + +This example will select, insert, update and delete from a connected SQL Server data source, using a parameterised command. The result of each command will be saved to the result. + +An [Commands][Command Types Commands] is used throughout this example, as it is the only type of [Command][Command Property] that allows you to execute and return the results of multiple commands. + +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; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter; DELETE FROM Table WHERE Id < @DeleteParameter; SELECT * FROM Table", "Parameters": { "SelectParameter": 3, InsertParameter1 = \"FirstColumn4\", InsertParameter2 = \"SecondColumn4\", "UpdateParameter": 3, "DeleteParameter": 3 }}`

In this example `($)Command` has been set using the following [Expression][]:

`new Commands("SELECT * FROM Table WHERE Id < @SelectParameter; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter; DELETE FROM Table WHERE Id < @DeleteParameter; SELECT * FROM Table", new {SelectParameter = 3, InsertParameter1 = "FirstColumn4", InsertParameter2 = "SecondColumn4", UpdateParameter = 3, DeleteParameter = 3})` | `($)Command` is a variable of type [Commands][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Running the [Commands][Command Types Commands] results in the variable `($)Result` being updated to the following: + +```json +[ + [ + { + "Id": 1, + "FirstColumn": "FirstColumn1", + "SecondColumn": "SecondColumn1" + }, + { + "Id": 2, + "FirstColumn": "FirstColumn2", + "SecondColumn": "SecondColumn2" + } + ], + 1, + 2, + 2, + [ + { + "Id": 3, + "FirstColumn": "FirstColumn3", + "SecondColumn": "SecondColumn3" + }, + { + "Id": 4, + "FirstColumn": "FirstColumn4", + "SecondColumn": "SecondColumn4" + } + ] +] +``` + +- The first item of `($)Result` represents the rows selected by the first select statement (`SELECT * FROM Table WHERE Id < @SelectParameter`). +- The second item of `($)Result` indicates that 1 row has been inserted into `Table` (`INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)`). +- The third item of `($)Result` indicates that 2 rows have been updated in `Table` (`UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter`). +- The fourth item of `($)Result` indicates that 2 rows have been deleted in `Table` (`DELETE FROM Table WHERE Id < @DeleteParameter`). +- The fifth item of `($)Result` represents the rows selected by the second select statement (`SELECT * FROM Table`). + +`Table` has been updated to: + +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | +| `4` | `"FirstColumn4"` | `"SecondColumn4"` | + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. For an example of a non parameterised command please see [Executing Multiple Commands (Unsafe)][] + +*** + +### Executing Multiple Commands (Unsafe) + +This example will select, insert, update and delete from a connected SQL Server data source, using [String Interpolation][] instead of parameters. The result of each command will be saved to the result. + +{{% alert title="Warning" color="warning" %}} +This example inserts data directly into the [Command](#command) instead of using parameters. This means the SQL in this example is susceptible to [SQL Injection](https://www.w3schools.com/sql/sql_injection.asp) and it is advised to use parameters to insert data into a command instead. + +Please see [Executing Multiple Commands (Safe)](#executing-multiple-commands-safe) for an example of a [Parameterised Command](#parameterised-commands). +{{% /alert %}} + +An [Commands][Command Types Commands] is used throughout this example, as it is the only type of [Command][Command Property] that allows you to execute and return the results of multiple commands. + +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"` | + +In this example assume the following variables have been set before the command has been executed: + +- `($)SelectParameter` with the value `3` +- `($)InsertParameter1` with the value `"FirstColumn4"` +- `($)InsertParameter2` with the value `"SecondColumn4"` +- `($)UpdateParameter` with the value `3` +- `($)DeleteParameter` with the value `3` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Command][Command Property] | `($)Command`, with value `{"CommandText": "SELECT * FROM Table WHERE Id < 3; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"FirstColumn1\", \"SecondColumn2\"); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < 3; DELETE FROM Table WHERE Id < 3; SELECT * FROM Table", "Parameters": null}`

In this example `($)Command` has been set using the following [Expression][]:

`new Commands($"SELECT * FROM Table WHERE Id < {($)SelectParameter}; INSERT INTO Table (FirstColumn, SecondColumn) VALUES ({($)InsertParameter1}, {($)InsertParameter2}); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < {($)UpdateParameter}; DELETE FROM Table WHERE Id < {($)DeleteParameter}; SELECT * FROM Table", null)` | `($)Command` is a variable of type [Commands][] | +| [Connection Details][Connection Details Property] | `($)ConnectionDetails`, with value `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | `($)ConnectionDetails` is a variable of type [SqlServerConnectionDetails][] | +| [Close Connection][Close Connection Property] | `($)CloseConnection`, with value `true` | `($)CloseConnection` is a variable of type [Boolean][] | +| [Result][Result Property] | `($)Result`, with no value | `($)Result` will be set to the type [dynamic][] | + +#### Result + +Running the [Commands][Command Types Commands] results in the variable `($)Result` being updated to the following: + +```json +[ + [ + { + "Id": 1, + "FirstColumn": "FirstColumn1", + "SecondColumn": "SecondColumn1" + }, + { + "Id": 2, + "FirstColumn": "FirstColumn2", + "SecondColumn": "SecondColumn2" + } + ], + 1, + 2, + 2, + [ + { + "Id": 3, + "FirstColumn": "FirstColumn3", + "SecondColumn": "SecondColumn3" + }, + { + "Id": 4, + "FirstColumn": "FirstColumn4", + "SecondColumn": "SecondColumn4" + } + ] +] +``` + +- The first item of `($)Result` represents the rows selected by the first select statement (`SELECT * FROM Table WHERE Id < @SelectParameter`). +- The second item of `($)Result` indicates that 1 row has been inserted into `Table` (`INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)`). +- The third item of `($)Result` indicates that 2 rows have been updated in `Table` (`UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter`). +- The fourth item of `($)Result` indicates that 2 rows have been deleted in `Table` (`DELETE FROM Table WHERE Id < @DeleteParameter`). +- The fifth item of `($)Result` represents the rows selected by the second select statement (`SELECT * FROM Table`). + +`Table` has been updated to: + +| Id | FirstColumn | SecondColumn | +|----|-------------|--------------| +| `3` | `"FirstColumn3"` | `"SecondColumn3"` | +| `4` | `"FirstColumn4"` | `"SecondColumn4"` | + +Note that using a [Parameterised Command][Parameterised Commands] helps prevent against [SQL Injection][], for more information please see [Parameterised Commands][]. + +*** + +## Properties + +### Command + +The [Command][Command Property] executed on the connected data source. There are multiple [Command Types][] that can be used, each with a different purpose: + +- [Command][Command Types Command]: Parses a single statement provided in the commandText, determining how the statement should be executed against the data source. If the commandText is a [Query Statement][Query Statements] the rows retrieved from the data source will be returned, otherwise if the commandText is a [Non Query Statement][Non Query Statements] the number of rows affected will be returned. +- [Commands][Command Types Commands]: Parses single or multiple statements provided in the commandText, determining how each statement should be executed against the data source. If a [Query Statement][Query Statements] is executed rows retrieved from the data source are added as an entry of the result, If a [Non Query Statement][Non Query Statements] is executed the number of rows affected is added as an entry of the result. +- [QueryCommand][Command Types QueryCommand]: Executes the given commandText as a [Query Statement][Query Statements], returning the rows retrieved from the data source. +- [NonQueryCommand][Command Types NonQueryCommand]: Executes the given commandText as a [Non Query Statement][Non Query Statements], returning the number of rows affected from the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [DataCommand][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Command][Command Types Command] with value `{"CommandText": "", "Parameters": null}` | + +### Connection Details + +The [Connection Details][Connection Details Property] object that includes all of the information required to connect to a data source, including: + +- [Connection String][Connection Strings] - must be provided in order to connect to a data source. The [Connection String][Connection Strings] is formatted differently depending on the type of data source that is being connected to, please see [Working with Data Sources][] for more information. + +For a list of currently supported connection details, please see [ConnectionDetails][] + +Note it is recommended to use a [Variable][] for [Connection Details][Connection Details Property] when it will be used across multiple Execute Command blocks, as using a variable will allow for reuse of the same connection. Using a [Literal][] to set the Connection Details will cause the connection to only be used once. + +| | | +|--------------------|---------------------------| +| Data Type | [ConnectionDetails][]| +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [SqlServerConnectionDetails][] with value `{"ConnectionString": "Server=localhost;Database=YourDatabase;Trusted_Connection=true;"}` | + +### Close Connection + +[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, this defaults to `false` if left blank, please see [Closing Connections][] for more information. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +### Result + +The object returned from the data source. + +Depending on the type of [Command][Command Property], the data returned within the [Result][Result Property] will vary. Please see [Command Types][] for more information on what data will be returned by each type. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][Variable Editor] | +| Default Value | `($)Result` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when the [Command][Command Property] is null. | +| | Thrown when the commandText within the [Command][Command Property] is null. | +| | Thrown when the [Connection Details][Connection Details Property] is null. | +| | Thrown when the connectionString within the [Connection Details][Connection Details Property] is null. | +| [PropertyEmptyException][] | Thrown when the commandText within the [Command][Command Property] is empty. | +| | Thrown when the connectionString within the [Connection Details][Connection Details Property] is empty. | +| [InvalidConnectionStringException][] | Thrown when an invalid connection string has been supplied (e.g. The connection string contains an invalid argument `"NotAnArgument = False"`). | +| | Thrown when a required connection string argument has not been supplied (e.g. The server requires encryption and the connection string contains `"Encrypt=False"`). | +| [CommandException][] | Thrown when the data source was not found or was not accessible. | +| | Thrown when an error occurs whilst trying to open a new connection. | +| | Thrown when a connection is successfully established but an error occurred during the login process. | +| | Thrown when the [Command][Command Property] contains syntax errors. The error will contain either a nested [SqlException][] with a corresponding [SqlException Error Code][SqlException Error Codes], or a nested [ParserException][] (Oracle Only). | +| | Thrown when the [Command][Command Property] is invalid for the table specified. | +| | Thrown when the [Command][Command Property] references a non-existent stored procedure. | +| | Thrown when parameters derives from [Array][] or [IEnumerable][] when a [Query Statement][Query Statements] is executed. | +| | Thrown when an [Command][] contains multiple statements. | +| | Thrown when a [Command][] or [Commands][] contains an [OracleBlockStatement][] statements. (Oracle Only)| + +## Remarks + +### Command Types + +There are multiple types of [Command][Command Property] that can be used, each with a different purpose: + +#### Command + +A [Command][] parses a single statement provided in the [commandText][Command.CommandText], determining how the statement should be executed against the data source. If the [commandText][Command.CommandText] is a [Query Statement][Query Statements] the rows retrieved from the data source will be returned, otherwise if the [commandText][Command.CommandText] is a [Non Query Statement][Non Query Statements] the number of rows affected will be returned. + +For a [Query Statement][Query Statements] (e.g. select and execute): + +| [Result][Result Property] will be set to | when | +|-|-| +| [List][]<[Structure][]> with a single item | Single item is returned | +| [List][]<[Structure][]> with many items | Many items are returned | +| [List][]<[Structure][]> with no items | No items are returned | + +For a [Non Query Statement][Non Query Statements] (e.g. insert, update, delete, etc) + +| [Result][Result Property] will be set to | when                                                         | +|-|-| +| [Int32][] with a value of `1` | Single row is affected | +| [Int32][] with a value greater than `1` | Many rows are affected | +| [Int32][] with a value of `0` | No rows are affected | + +If multiple statements are provided in [CommandText][Command.CommandText], the block will throw a [CommandException][] as this type can only run single statements. + +If performance is a key consideration it is recommended to use a [QueryCommand][Command Types QueryCommand] or [NonQueryCommand][Command Types NonQueryCommand] instead of [Command][] as they do not parse the [commandText][Command.CommandText]. + +#### Commands + +A [Commands][] parses single or multiple statements provided in the [commandText][Commands.CommandText], determining how each statement should be executed against the data source. If a [Query Statement][Query Statements] is executed rows retrieved from the data source are added as an entry of the result, If a [Non Query Statement][Non Query Statements] is executed the number of rows affected is added as an entry of the result. + +For each [Query Statement][Query Statements] (e.g. select and execute): + +| [Result][Result Property] will have the following entry added | when | +|-|-| +| [List][]<[Structure][]> with a single item | Single item is returned | +| [List][]<[Structure][]> with many items | Many items are returned | +| [List][]<[Structure][]> with no items | No items are returned | + +For each [Non Query Statement][Non Query Statements] (e.g. insert, update, delete, etc) + +| [Result][Result Property] will have the following entry added | when                                   | +|-|-| +| [Int32][] with a value of `1` | Single row is affected | +| [Int32][] with a value greater than `1` | Many rows are affected | +| [Int32][] with a value of `0` | No rows are affected | + +If performance is a key consideration it is recommended to use a [QueryCommand][Command Types QueryCommand] or [NonQueryCommand][Command Types NonQueryCommand] instead of [Commands][] as they do not parse the [commandText][Commands.CommandText]. + +Note that the [Commands][] should not be used for commands that have dependency between their statements (e.g. Cursors and Variables). Please see [Complex Commands][] for more information on how to deal with these. + +#### QueryCommand + +A [QueryCommand][] executes the given [commandText][QueryCommand.CommandText] as a [Query Statement][Query Statements], returning the rows retrieved from the data source. If the [commandText][QueryCommand.CommandText] contains multiple select statements, only the results of the first [Query Statement][Query Statements] will be returned. + +For a [Query Statement][Query Statements] (e.g. select): + +| [Result][Result Property] will be set to | when | +|-|-| +| [List][]<[Structure][]> with a single item | Single item is returned | +| [List][]<[Structure][]> with many items | Many items are returned | +| [List][]<[Structure][]> with no items | No items are returned | + +For a [Non Query Statement][Non Query Statements] (e.g. insert, update, delete, etc) + +| [Result][Result Property] will be set to                                                                                        | when | +|-|-| +| `[]` | always, as [Non Query Statements][] do not return data | + +Note use a [QueryCommand][] for commands that have dependency between their statements (e.g. Cursors and Variables) and return data from the data source. Please see [Complex Commands][] for more information. + +#### NonQueryCommand + +A [NonQueryCommand][] executes the given [commandText][NonQueryCommand.CommandText] as a [Non Query Statement][Non Query Statements], returning the number of rows affected from the data source. If the command contains multiple statements, the sum of all the results will be returned. + +For a [Query Statement][Query Statements] (e.g. select): + +| [Result][Result Property] will be set to                                                                                 | when | +|-|-| +| [Int32][] with a value of `-1` | always, as [Query Statements][] do not return data | + +For a [Non Query Statement][Non Query Statements] (e.g. insert, update, delete, etc) + +| [Result][Result Property] will be set to | when | +|-|-| +| [Int32][] with a value of `1` | Single row is affected | +| [Int32][] with a value greater than `1` | Many rows are affected | +| [Int32][] with a value of `0` | No rows are affected | + +Note use a [NonQueryCommand][] for commands that have dependency between their statements (e.g. Cursors and Variables) and return the number of rows affected. Please see [Complex Commands][] for more information. + +### Statement Types + +There are two categories of statements [Query][Query Statements] and [Non Query][Non Query Statements]. + +#### Query Statements + +Query Statements are used to retrieve data from a data source, for example selecting all rows from a table in a database, Query Statements return the data selected by the Statement as a [List][]<[Structure][]> when used in an [Command][Command Types Command], an [Commands][Command Types Commands], or a [QueryCommand][Command Types QueryCommand]. If a Query Statement is used in a [NonQueryCommand][Command Types NonQueryCommand] `-1` will be returned as Query Statements do not affect rows. + +Examples of Query Statements can be found here: + +- [Selecting Rows][] +- [Using Functions][] +- [Using Multiple Functions][] +- [Executing Multiple Commands (Safe)][] +- [Executing Multiple Commands (Unsafe)][] + +A Query Statement can use any object as a parameter. Objects that derive from [Array][] or [IEnumerable][] can only be used for clauses that accept list values (e.g. `IN`, `ANY`, `ALL`), if they are used in other clauses the block will throw a [CommandException][]. + +#### Non Query Statements + +Non Query Statements are used to manipulate the data within a data source, for example deleting all rows from a table in a database, Non Query Statements return the number of rows affected by the Statement as an [Int32][] value when used in an [Command][Command Types Command], an [Commands][Command Types Commands], or a [NonQueryCommand][Command Types NonQueryCommand]. If a Non Query Statement is used in a [QueryCommand][Command Types QueryCommand] `null` will be returned as Non Query Statements do not return data. + +Examples of Non Query Statements can be found here: + +- [Inserting Rows][] +- [Updating Rows][] +- [Deleting Rows][] +- [Executing Multiple Commands (Safe)][] +- [Executing Multiple Commands (Unsafe)][] + +A Non Query Statement can use any object as a parameter. If an object that derives from [Array][] or [IEnumerable][] is used, the Non Query Statement will be executed for each item in the [Array][] or [IEnumerable][] and the sum of all the results will be returned. + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the [Command][Command Property] is executed. + +The `@` symbol denotes a parameter within the [CommandText][DataCommand.CommandText] (e.g. `"SELECT * FROM Table WHERE Name = @Parameter"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +[Query Statements][] can use any object as a parameter. Objects that derive from [Array][] or [IEnumerable][] can only be used for clauses that accept list values (e.g. `IN`, `ANY`, `ALL`), if they are used in other clauses the block will throw a [CommandException][]. + +[Non Query Statements][] can use any object as a parameter. If an object that derives from [Array][] or [IEnumerable][] is used, the Non Query Statement will be executed for each item in the [Array][] or [IEnumerable][] and the sum of all the results will be returned. + +For both [Query Statements][] and [Non Query Statements][], an SqlException is thrown if a parameter is missing from the [Command][Command Property] and the [CommandText][DataCommand.CommandText] contains a parameter (e.g. `{"CommandText": "SELECT * FROM Table WHERE Name = @Parameter", "Parameters": {"IncorrectParameter": 0}}`). + +### Complex Commands + +Complex commands (e.g. Cursors and Variables) that contain dependency between their statements cannot be used with [Commands][Command Types Commands], as the parsing performed by the block will cause each statement of [CommandText][DataCommand.CommandText] to be run individually instead of running the [CommandText][DataCommand.CommandText] as a whole. + +For statements with this type of dependency use either [QueryCommand][Command Types QueryCommand] or [NonQueryCommand][Command Types NonQueryCommand], depending on whether data from the data source or the number of rows affected is returned. + +### Connection Strings + +A connection string must be provided within the [Connection Details][Connection Details Property] in order to connect to a data source. The connection string is formatted differently depending on the type of data source, please see [Working with Data Sources][] for more information. + +Please see [Working with Data Sources][] for a list of supported data sources and how to construct valid connection strings for them. + +### Opening Connections + +The Execute Command block automatically handles creating and opening connections for the specified [Connection Details][Connection Details Property] using the following rules: + +- If a connection does not exist, a new connection will be created, opened and used when the block runs. +- If a connection already exists but is closed, the connection will be opened and used when the block runs. +- If a connection already exists and is open, the connection will used the block runs. + +If a [Variable][] is used to pass in the [Connection Details][Connection Details Property] it can be used to keep the connection alive across multiple Execute Command blocks as long as [Close Connection][Close Connection Property] is set to `false`. Keeping the connection open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening connections for each execution. + +If a [Literal][] or an [Expression][] is used to create the [Connection Details][Connection Details Property] a new connection will always be made when the Execute Command block runs and if [Close Connection][Close Connection Property] is set to `false` the connection will be closed automatically at some point after the block finishes and before the flow ends. + +For information on how to explicitly close a connection, please see [Closing Connections][]. + +### Closing Connections + +Connections can be explicitly closed by setting [Close Connection][Close Connection Property] to `true`. This causes the connection to be closed after the [Command][Command Property] has been executed. + +If a [Variable][] is used to pass in the [Connection Details][Connection Details Property] and [Close Connection][Close Connection Property] is set to `false` the connection will be closed when the [Variable][] goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see [Variables][]. + +If a [Literal][] or an [Expression][] is used to create the [Connection Details][Connection Details Property] and [Close Connection][Close Connection Property] is set to `false` the connection will be closed automatically at some point after the Execute Command block finishes and before the flow ends. + +For information on how to open a connection, please see [Opening Connections][]. + +### Why does the Result property return a dynamic data type? + +The decision for the [Result][Result Property] to return a [dynamic data type][dynamic] rather than a specific type, was to avoid users having to [cast][Object Casting] the [Result][Result Property] to its correct type to be able to use all of its properties. + +As a result, any issues with using the [Result][Result 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 [Result][Result Property] to its correct type. + +### RunAs + +RunAs can be used to connect to a database as a Windows user, rather than a SQL user. + +To connect as a Windows user: +- An appropriate connection string (e.g. [Oracle][OracleConnectionStringIntegratedSecurity], [SQL Server][SqlConnectionStringTrustedConnection]) must be specified in the [Connection Details][Connection Details Property]. +- [UserCredentials][] for the Windows user must be specified in the [Run As property][RunAsProperty]. + +If connecting to a local database, the [UserCredentials][] must specify the [LogonType][] to be `LogonType.Network`; if connecting to a remote database, the [LogonType][] must be `LogonType.NewCredentials`. + +### Known Limitations + +When using a [Parameterised Command][Parameterised Commands] to execute a stored procedure, it is not possible to write back to output parameters. + +[Command Property]: {{< ref "#command" >}} +[Connection Details Property]: {{< ref "#connection-details" >}} +[Close Connection Property]: {{< ref "#close-connection" >}} +[Result Property]: {{< ref "#result-8" >}} + +[Selecting Rows]: {{< ref "#selecting-rows">}} +[Inserting Rows]: {{< ref "#inserting-rows">}} +[Updating Rows]: {{< ref "#updating-rows">}} +[Deleting Rows]: {{< ref "#deleting-rows">}} +[Executing Multiple Commands (Safe)]: {{< ref "#executing-multiple-commands-safe">}} +[Executing Multiple Commands (Unsafe)]: {{< ref "#executing-multiple-commands-unsafe">}} +[Using Functions]: {{< ref "#using-functions">}} +[Using Multiple Functions]: {{< ref "#using-multiple-functions">}} +[Executing a Parameterised Command]: {{< ref "#executing-a-parameterised-command">}} + +[Command Types]: {{< ref "#command-types">}} +[Command Types Command]: {{< ref "#command-1">}} +[Command Types Commands]: {{< ref "#commands">}} +[Command Types QueryCommand]: {{< ref "#querycommand">}} +[Command Types NonQueryCommand]: {{< ref "#nonquerycommand">}} + +[Query Statements]: {{< ref "#query-statements">}} +[Non Query Statements]: {{< ref "#non-query-statements">}} + +[Connection Strings]: {{< ref "#connection-strings">}} +[Parameterised Commands]: {{< ref "#parameterised-commands">}} +[Complex Commands]: {{< ref "#complex-commands">}} +[Opening Connections]: {{< ref "#opening-connections">}} +[Closing Connections]: {{< ref "#closing-connections">}} + +[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" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[InvalidConnectionStringException]: {{< url path="Cortex.Reference.Exceptions.Data.InvalidConnectionStringException.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} + +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[TConnectionDetails]: {{< 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" >}} +[Array]: {{< url path="Cortex.Reference.DataTypes.Collections.Array.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} + +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[DataCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.CommandText" >}} + +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Command.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Command.CommandText" >}} + +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[Commands.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.CommandText" >}} + +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[QueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.CommandText" >}} + +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[NonQueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.CommandText" >}} + +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.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" >}} +[String Interpolation]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.ConvertingObjectsToText.StringInterpolation" >}} +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} +[Connection String Formats]: {{< url path="ConnectionStrings.MainDoc" >}} +[SqlException Error Codes]: {{< url path="MSDocs.SqlServer.ErrorCodes" >}} +[SqlException]: {{< url path="MSDocs.SqlServer.SqlException" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} +[RunAsProperty]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.RunAsProperty" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} +[SQL Injection]: {{< url path="W3.SqlInjection" >}} + +[SqlConnectionStringTrustedConnection]: {{< url path="ConnectionStrings.SqlConnectionTrustedConnection" >}} +[OracleConnectionStringIntegratedSecurity]: {{< url path="ConnectionStrings.OracleConnectionIntegratedSecurity" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Blocks/date-and-time/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/_index.md new file mode 100644 index 000000000..442888370 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/date-and-time/_index.md @@ -0,0 +1,5 @@ +--- +title: "Date & Time" +linkTitle: "Date & Time" +description: "Blocks related to working with Date and Time." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/_index.md new file mode 100644 index 000000000..b273f6313 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/_index.md @@ -0,0 +1,5 @@ +--- +title: "Add Time Period" +linkTitle: "Add Time Period" +description: "Add a time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) to a date time." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/add-time-period-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/add-time-period-block.md new file mode 100644 index 000000000..1932df472 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/date-and-time/add-time-period/add-time-period-block.md @@ -0,0 +1,157 @@ +--- +title: "Add Time Period" +linkTitle: "Add Time Period" +description: "Adds a Time Period to a specified Date Time." +--- + +{{< figure src="/blocks/Cortex_Blocks_DateAndTime_AddTimePeriod_AddTimePeriodBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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`
Months: `0`
Days: `0`
Hours: `0`
Minutes: `0`
Seconds: `0`
Milliseconds: `0`| + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when adding [Time Period][TimePeriod Property] to [Date Time][DateTime Property] will result in the [Date Time][DateTime Property] being less than `0001-01-01T00:00:00+00:00`. See [Property Less Than Minimum Value][].| +| | Thrown when adding [Time Period][TimePeriod Property] to [Date Time][DateTime Property] will result in the [Date Time][DateTime Property] being greater than `9999-12-31T23:59:59+00:00`. See [Property Greater Than Maximum Value][]. | + +## 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][]. + +### Order of calculations + +When adding a [Time Period][TimePeriod Property], the block will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds. + +### Addition of Months + +When adding months to the [Date Time][DateTime Property], 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`). + +### Daylight Savings + +This block copes with UTC time offsets but does not know anything about which time zone the [Date Time][DateTime Property] represents; as a result it cannot take daylight savings into account as these are related to time zones rather than UTC time offsets. + +[DateTime Property]: {{< ref "#date-time" >}} +[TimePeriod Property]: {{< ref "#time-period" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} +[Property Greater Than Maximum Value]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyGreaterThanMaximumValue" >}} +[Property Less Than Minimum Value]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyLessThanMinimumValue" >}} + +[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" >}} + +[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/2024.9/Reference/Blocks/date-and-time/convert-date-time/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/_index.md new file mode 100644 index 000000000..c4089d580 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/_index.md @@ -0,0 +1,5 @@ +--- +title: "Convert Date Time" +linkTitle: "Convert Date Time" +description: "Convert a date time to and from text." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/convert-date-time-to-text-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/convert-date-time-to-text-block.md new file mode 100644 index 000000000..7853340df --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/convert-date-time-to-text-block.md @@ -0,0 +1,254 @@ +--- +title: "Convert Date Time To Text" +linkTitle: "Convert Date Time To Text" +description: "Converts a Date Time to Text." +--- + +{{< figure src="/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertDateTimeToTextBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/date-and-time/convert-date-time/convert-text-to-date-time-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/convert-date-time/convert-text-to-date-time-block.md new file mode 100644 index 000000000..c2a93ad96 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertTextToDateTimeBlock.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/2024.9/Reference/Blocks/date-and-time/get-date-time/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/get-date-time/_index.md new file mode 100644 index 000000000..fa05212da --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/date-and-time/get-date-time/get-current-date-time-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/get-date-time/get-current-date-time-block.md new file mode 100644 index 000000000..58759f529 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_GetDateTime_GetCurrentDateTimeBlock.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/2024.9/Reference/Blocks/date-and-time/get-date-time/get-date-time-component-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/get-date-time/get-date-time-component-block.md new file mode 100644 index 000000000..3e2a32399 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_GetDateTime_GetDateTimeComponentBlock.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/2024.9/Reference/Blocks/date-and-time/get-time-period/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/get-time-period/_index.md new file mode 100644 index 000000000..631288791 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/date-and-time/get-time-period/get-time-period-between-date-times-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/get-time-period/get-time-period-between-date-times-block.md new file mode 100644 index 000000000..e4fb7740f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_GetTimePeriod_GetTimePeriodBetweenDateTimesBlock.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/2024.9/Reference/Blocks/date-and-time/is-date-time/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/is-date-time/_index.md new file mode 100644 index 000000000..0bc30351e --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-after-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-after-block.md new file mode 100644 index 000000000..18dc3cbd2 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeAfterBlock.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/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-before-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-before-block.md new file mode 100644 index 000000000..107d3c2af --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBeforeBlock.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/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-between-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-between-block.md new file mode 100644 index 000000000..f4e3f95eb --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBetweenBlock.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/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-equal-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/is-date-time/is-date-time-equal-block.md new file mode 100644 index 000000000..1c0da869a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeEqualBlock.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/2024.9/Reference/Blocks/date-and-time/subtract-time-period/_index.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/subtract-time-period/_index.md new file mode 100644 index 000000000..95e6ebff1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/date-and-time/subtract-time-period/subtract-time-period-block.md b/content/en/docs/2024.9/Reference/Blocks/date-and-time/subtract-time-period/subtract-time-period-block.md new file mode 100644 index 000000000..be69f77f9 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_DateAndTime_SubtractTimePeriod_SubtractTimePeriodBlock.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`
Months: `0`
Days: `0`
Hours: `0`
Minutes: `0`
Seconds: `0`
Milliseconds: `0`| + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyValueOutOfRangeException][] | Thrown when subtracting [Time Period][TimePeriod Property] from [Date Time][DateTime Property] will result in the [Date Time][DateTime Property] being less than `0001-01-01T00:00:00+00:00`. See [Property Less Than Minimum Value][].| +| | Thrown when subtracting [Time Period][TimePeriod Property] from [Date Time][DateTime Property] will result in the [Date Time][DateTime Property] being greater than `9999-12-31T23:59:59+00:00`. See [Property Greater Than Maximum Value][]. | + +## 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][]. + +### Order of calculations + +When subtracting a [Time Period][TimePeriod Property], the block will first subtract years, followed by months, days, hours, minutes, seconds and finally milliseconds. + +### Subtraction of Months + +When subtracting months from the [Date Time][DateTime Property], 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`). + +### Daylight Savings + +This block copes with UTC time offsets but does not know anything about which time zone the [Date Time][DateTime Property] represents; as a result it cannot take daylight savings into account as these are related to time zones rather than UTC time offsets. + +[DateTime Property]: {{< ref "#date-time" >}} +[TimePeriod Property]: {{< ref "#time-period" >}} + +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} +[Property Greater Than Maximum Value]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyGreaterThanMaximumValue" >}} +[Property Less Than Minimum Value]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.PropertyLessThanMinimumValue" >}} + +[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" >}} + +[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/2024.9/Reference/Blocks/decisions/_index.md b/content/en/docs/2024.9/Reference/Blocks/decisions/_index.md new file mode 100644 index 000000000..15b7f418c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/decisions/_index.md @@ -0,0 +1,5 @@ +--- +title: "Decisions" +linkTitle: "Decisions" +description: "Blocks related to making decisions and branching the path a flow execution takes." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/decisions/if/_index.md b/content/en/docs/2024.9/Reference/Blocks/decisions/if/_index.md new file mode 100644 index 000000000..cd4e027e1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/decisions/if/_index.md @@ -0,0 +1,5 @@ +--- +title: "If Else" +linkTitle: "If Else" +description: "Perform if-else like conditional decision making." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-null-exit-bottom-block-1.md b/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-null-exit-bottom-block-1.md new file mode 100644 index 000000000..93099fb1b --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-null-exit-bottom-block-1.md @@ -0,0 +1,96 @@ +--- +title: "If Null Exit Bottom" +linkTitle: "If Null Exit Bottom" +description: "Checks if a given value is `null`; if so the flow execution exits via the block's bottom port, otherwise it exits via the right port." +--- + +{{< figure src="/blocks/Cortex_Blocks_Decisions_If_IfNullExitBottomBlock_1.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/decisions/if/if-null-exit-right-block-1.md b/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-null-exit-right-block-1.md new file mode 100644 index 000000000..2b7cd3735 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Decisions_If_IfNullExitRightBlock_1.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/2024.9/Reference/Blocks/decisions/if/if-true-exit-bottom-block.md b/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-true-exit-bottom-block.md new file mode 100644 index 000000000..2e2c3cdf4 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Decisions_If_IfTrueExitBottomBlock.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/2024.9/Reference/Blocks/decisions/if/if-true-exit-right-block.md b/content/en/docs/2024.9/Reference/Blocks/decisions/if/if-true-exit-right-block.md new file mode 100644 index 000000000..9aab2593f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Decisions_If_IfTrueExitRightBlock.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/2024.9/Reference/Blocks/email/_index.md b/content/en/docs/2024.9/Reference/Blocks/email/_index.md new file mode 100644 index 000000000..da41aa5a8 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/email/send-email/_index.md b/content/en/docs/2024.9/Reference/Blocks/email/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/email/send-email/send-email-using-smtp-server-block.md b/content/en/docs/2024.9/Reference/Blocks/email/send-email/send-email-using-smtp-server-block.md new file mode 100644 index 000000000..0c903c68e --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Email_SendEmail_SendEmailUsingSmtpServerBlock.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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email to multiple recipients + +This example will send an email from `sender@gmail.com` to `recipient1@outlook.com`, `recipient2@outlook.com` and `recipient3@outlook.com`. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": "recipient1@outlook.com"}, {"Name": null, "Address": "recipient2@outlook.com"}, {"Name": null, "Address": "recipient3@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient1@outlook.com"), new EmailAddress("recipient2@outlook.com"), new EmailAddress("recipient3@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient1@outlook.com`, `recipient2@outlook.com` and `recipient3@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with a CC or BCC recipient + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com` with `cc@outlook.com` and `bcc@outlook.com` as the [CC][CC Glossary] and [BCC][BCC Glossary] recipients for the email respectively. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List(){ new EmailAddress("cc@outlook.com") }, bcc: new List(){ new EmailAddress("bcc@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`. Both `cc@outlook.com` and `bcc@outlook.com` will also recieve copies of the email as they are listed as [CC][CC Glossary] and [BCC][BCC Glossary] recipients, and then the session is closed. + +*** + +### Sending an email with multiple CC or BCC recipients + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com` with `cc1@outlook.com` and `cc2@outlook.com` as the [CC][CC Glossary] recipients and `bcc1@outlook.com` and `bcc2@outlook.com` as the [BCC][BCC Glossary] recipients for the email. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": [{"Name": null, "Address": "cc1@outlook.com"}, {"Name": null, "Address": "cc2@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc1@outlook.com"}, {"Name": null, "Address": "bcc2@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List(){ new EmailAddress("cc1@outlook.com"), new EmailAddress("cc2@outlook.com") }, bcc: new List(){ new EmailAddress("bcc1@outlook.com"), new EmailAddress("bcc2@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`. Both `cc1@outlook.com` and `cc2@outlook.com` will also recieve copies of the email as they are listed as [CC][CC Glossary] recipients, and both `bcc1@outlook.com` and `bcc2@outlook.com` will recieve copies of the email as they are listed as [BCC][BCC Glossary] recipients. Finally, the session is closed. + +*** + +### Sending an email with a different priority + +This example will send an email with [Urgent][] priority 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 set to `true` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information on: + +- What priorities an email can be sent as, see [EmailMessagePriority][] +- The effect of changing the [Priority][] of the [Email Message][Email Message Property], see [How does Priority affect sending an email?][] +- 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": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [BodyFormat][] is `null`, the email will be sent with a [Text][] body.| +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Urgent][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with an HTML body + +This example will send an email with an [HTML][] body 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 set to `true` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information on: + +- What other body formats an email can be sent with, see [EmailMessageBodyFormat][] +- The effect of changing the [BodyFormat][] of the [Email Message][Email Message Property], see [How does BodyFormat affect sending an email?][] +- 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": "EmailMessageBodyFormat.Html", "Body": "

Example email body

", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Html, body: "

Example email body

", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] is `null`, the email will be sent with [Normal][] priority. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and an [HTML][] body of `"

Example email body

"`, and then the session is closed. + +*** + +### Sending an email with a single attachment + +This example will send an email with a single attachment, `attachment.txt`, from `sender@gmail.com` to `recipient@outlook.com`. The attachment is located at `C:\attachment.txt` on the server executing the flow. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be set to `true` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information on: + +- Email attachments, see [Attachments][Attachments Remarks] +- 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": ["C:\\attachment.txt"]}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List(){ @"C:\attachment.txt" })` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.

The [Attachments][Attachments Remarks] are added to the email by providing file paths pointing to the files to be attached to the email. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority containing a text file attachment, `attachment.txt`, is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with multiple attachments + +This example will send an email with mutiple attachments, `attachment1.txt` and `attachment2.txt` from `sender@gmail.com` to `recipient@outlook.com`. The attachments are located at the paths `C:\attachment1.txt` and `C:\attachment2.txt` on the server executing the flow. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be set to `true` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information on: + +- Email attachments, see [Attachments][Attachments Remarks] +- 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": ["C:\\attachment1.txt", "C:\\attachment2.txt"]}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List(){ @"C:\attachment1.txt", @"C:\attachment2.txt" })` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.

The [Attachments][Attachments Remarks] are added to the email by providing file paths pointing to the files to be attached to the email. | +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority containing two text file attachments, `attachment1.txt` and `attachment2.txt`, is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with UseSsl set to false + +This example will send an email from `sender@outlook.com` to `recipient@outlook.com`. The example uses the [SMTP][] server hosted at `smtp-mail.outlook.com` on [Port][] `587` which requires [UseSsl][] to be set to `false` within the [Basic Email Session Details][Basic Email Session Details Property]. + +For more information on 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@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Basic Email Session Details][Basic Email Session Details Property] | `($)BasicEmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp-mail.outlook.com", "Port": 587, "UseSsl": false}, "Credentials": {"Domain": null, "Username": "sender@outlook.com", "Password": "encryptedPassword"}}`

In this example `($)BasicEmailSessionDetails` has been set up using the following [Expression][]:

`new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp-mail.outlook.com", 587, false), credentials: new UserCredentials("sender@outlook.com", "encryptedPassword"))` | `($)BasicEmailSessionDetails` is a variable of type [BasicEmailSessionDetails][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@outlook.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +## Properties + +### Email Message + +The [Email Message][Email Message Property] to send via the [SMTP][] server specified in the [Basic Email Session Details][Basic Email Session Details Property]. This property contains all of the information in relation to the email to be sent, these are: + +- [To][] +- [From][] +- [Cc][] +- [Bcc][] +- [Priority][] +- [Subject][] +- [BodyFormat][] +- [Body][] +- [Attachments][] + +Note that if the properties [Priority][] and [BodyFormat][] are set to `null` when [creating an EmailMessage using a constructor][], the email will be sent with [Normal][] priority and with a text body. + +For more detailed information on each of the properties, see [EmailMessage][]. + +||| +|----------|----------| +| Data Type | [EmailMessage][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [EmailMessage][] with value shown below: | + +```json +{ + "To": [ + { + "Name": null, + "Address": "" + } + ], + "From": { + "Name": "", + "Address": "" + }, + "Cc": [], + "Bcc": [], + "Priority": "EmailMessagePriority.Normal", + "Subject": "", + "BodyFormat": "EmailMessageBodyFormat.Text", + "Body": "", + "Attachments": [] +} +``` + +### Basic Email Session Details + +The [Basic Email Session Details][Basic Email Session Details Property] object that includes all of the information required to open and maintain a session with an [SMTP][] server, including: + +- [ServerDetails][ServerDetails Property] - must be provided in order to connect to an [SMTP][] server. This object contains the properties [Host][], [Port][] and [UseSsl][]. For more information on: + - Supported server address formats, see [Supported formats for ServerDetails.Host][]. + - When [UseSsl][] should be set to `true` or `false`, see [Setting UseSsl][]. +- [Credentials][Credentials Property] - must be provided in order to connect to an [SMTP][] server. This object contains the properties [Username][] and [Password][] to be used for authentication. For more information, see [Setting Credentials][]. + +If the [Close Session][Close Session Property] property is set to `false`, then the session will be kept open and can be used in subsequent Send Email Using SMTP Server blocks which improves performance, see [Opening Sessions][] for more information. + +For more detailed information on each of the properties, see [BasicEmailSessionDetails][]. + +||| +|----------|----------| +| Data Type | [BasicEmailSessionDetails][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)BasicEmailSessionDetails` with no value | + +### Close Session + +[Close Session][Close Session Property] can be specified to choose whether the session is closed or is kept open for use on subsequent Send Email Using SMTP Server blocks, this defaults to `false` if left blank, please see [Closing Sessions][Closing Sessions] for more information. + +||| +|-----------------|----------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [ArgumentException][] |Thrown when [BodyFormat][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessageBodyFormat][] values (e.g. `(EmailMessageBodyFormat)10`).| +| |Thrown when [Priority][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessagePriority][] values (e.g. `(EmailMessagePriority)10`).| +| |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] is empty (i.e. `""`), contains only whitespace (i.e. `" "`) or contains the NUL character (i.e. `\0`).| +| [ArgumentNullException][] |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] is `null`.| +| [EmailSessionException][] |Thrown when an invalid [Port][] is provided in the [ServerDetails][] within the [Basic Email Session Details][Basic Email Session Details Property]. For more information, see [Invalid Port][].| +| |Thrown when an invalid [Host][] is provided in the [ServerDetails][] within the [Basic Email Session Details][Basic Email Session Details Property]. For more information, see [Invalid Host][].| +| |Thrown when a connection cannot be established; this typically occurs when [UseSsl][] within [Basic Email Session Details][Basic Email Session Details Property] is set to `false` with a [Port][] which requires it to be set to `true`. For more information, see [SSL Required][]. | +| |Thrown when a connection cannot be established; this typically occurs when [UseSsl][] within [Basic Email Session Details][Basic Email Session Details Property] is set to `true` with a [Port][] which requires it to be set to `false`. For more information, see [SSL Unsupported][]. | +| |Thrown when the [TLS][]/[SSL][] certificate has expired on the [Host][] or is untrusted or invalid. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when a locally installed anti-virus software replaces the [TLS][]/[SSL][] certificate in order to scan web traffic. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when the [CRL][] (Certificate Revocation List) server for the [TLS][]/[SSL][] certificate is down. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when the [Username][] and [Password][] in the [UserCredentials][] within [Basic Email Session Details][Basic Email Session Details Property] is incorrect. For more information, see [Invalid User Credentials][]. | +| [FileNotFoundException][] |Thrown when a non-existent file path is provided in [Attachments][] within [Email Message][Email Message Property]. | +| [IOException][] |Thrown when the desired socket is held by another process; re-running the flow typically solves this. | +| |Thrown when a file path within [Attachments][] within the [Email Message][Email Message Property] contains leading spaces.| +| |Thrown when a file path within [Attachments][] within the [Email Message][Email Message Property] contains invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`).| +| [PathTooLongException][] |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] exceeds the system-defined maximum length (typically 32,767).| +| [PropertyNullException][] |Thrown when the [Basic Email Session Details][Basic Email Session Details Property] is `null`. | +| |Thrown when the [UserCredentials][] within [Basic Email Session Details][Basic Email Session Details Property] is `null`. | +| |Thrown when the [ServerDetails][] within [Basic Email Session Details][Basic Email Session Details Property] is `null`. | +| |Thrown when the [Host][] in [ServerDetails][] within [Basic Email Session Details][Basic Email Session Details Property] is `null`. | +| |Thrown when the [Email Message][Email Message Property] is `null`. | +| |Thrown when the [To][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [From][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is `null`. | +| [PropertyEmptyException][] |Thrown when the [Host][] in [ServerDetails][] within [Basic Email Session Details][Basic Email Session Details Property] is empty (i.e. `""`). | +| |Thrown when the [To][] within [Email Message][Email Message Property] is empty (i.e. `[]`). | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is empty (i.e. `""`). | +| [PropertyValueOutOfRangeException][] |Thrown when the [Port][] in the [ServerDetails][] within [Basic Email Session Details][Basic Email Session Details Property] is below `1` or above `65535`. For more information, see [Property Is Invalid][]. | +| [SmtpCommandException][] |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is not of the correct format ([RFC 5321][]).| +| |Thrown when the combined size of all of the attachments in the list of [Attachments][] within the [Email Message][Email Message Property] is greater than the limit specified by the email service provider; for [Outlook][] this is `20 MB` and for [Gmail][] this is `25 MB`.| +| [UnauthorizedAccessException][] |Thrown when access is denied to a file provided in [Attachments][] within [Email Message][Email Message Property].| +| |Thrown when a file path within the [Attachments][] property within [Email Message][Email Message Property] points to a folder.| + +## Remarks + +### How does Priority affect sending an email? + +An email sent with [Urgent][] or [NonUrgent][] priority will have its priority displayed differently depending on the email client. For example, [Outlook][] displays an email that has an [Urgent][] priority with a red exclamation mark like so: + +{{< figure src="/images/send-email-using-smtp-server-important-email.png" >}} + +For more information on how the priority of an email will be displayed, see the help provided by the respective email client. + +### How does BodyFormat affect sending an email? + +An email sent with an [HTML][] body will have its body displayed as an HTML page instead of as plain text. How the email looks in the email client may differ depending on the email client in use. For example, if the [Email Message][Email Message Property] has its [BodyFormat][] set to [HTML][] and the [Body][] has a value of: + +```json +"

Example header text

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/2024.9/Reference/Blocks/flows/_index.md b/content/en/docs/2024.9/Reference/Blocks/flows/_index.md new file mode 100644 index 000000000..3a64c9787 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/flows/end-flow/_index.md b/content/en/docs/2024.9/Reference/Blocks/flows/end-flow/_index.md new file mode 100644 index 000000000..df9410cb5 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/flows/end-flow/end-flow-block.md b/content/en/docs/2024.9/Reference/Blocks/flows/end-flow/end-flow-block.md new file mode 100644 index 000000000..b5b228d9b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Flows_EndFlow_EndFlowBlock.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/2024.9/Reference/Blocks/flows/run-flow/_index.md b/content/en/docs/2024.9/Reference/Blocks/flows/run-flow/_index.md new file mode 100644 index 000000000..fb5ca15c1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/flows/run-flow/run-flow-async-block.md b/content/en/docs/2024.9/Reference/Blocks/flows/run-flow/run-flow-async-block.md new file mode 100644 index 000000000..854ca8870 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Flows_RunFlow_RunFlowAsyncBlock.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/2024.9/Reference/Blocks/flows/run-flow/run-flow-block.md b/content/en/docs/2024.9/Reference/Blocks/flows/run-flow/run-flow-block.md new file mode 100644 index 000000000..e18e12e2f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Flows_RunFlow_RunFlowBlock.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/2024.9/Reference/Blocks/flows/start-flow/_index.md b/content/en/docs/2024.9/Reference/Blocks/flows/start-flow/_index.md new file mode 100644 index 000000000..80df19ef8 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/flows/start-flow/start-flow-block.md b/content/en/docs/2024.9/Reference/Blocks/flows/start-flow/start-flow-block.md new file mode 100644 index 000000000..984fbcba4 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Flows_StartFlow_StartFlowBlock.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/2024.9/Reference/Blocks/google-workspace/_index.md b/content/en/docs/2024.9/Reference/Blocks/google-workspace/_index.md new file mode 100644 index 000000000..8d6e24e3f --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/google-workspace/gmail/_index.md b/content/en/docs/2024.9/Reference/Blocks/google-workspace/gmail/_index.md new file mode 100644 index 000000000..f53ba8b4b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/google-workspace/gmail/send-email/_index.md b/content/en/docs/2024.9/Reference/Blocks/google-workspace/gmail/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/google-workspace/gmail/send-email/send-email-using-gmail-block.md b/content/en/docs/2024.9/Reference/Blocks/google-workspace/gmail/send-email/send-email-using-gmail-block.md new file mode 100644 index 000000000..2862a63b3 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_GoogleWorkspace_Gmail_SendEmail_SendEmailUsingGmailBlock.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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email to multiple recipients + +This example will send an email from `sender@gmail.com` to `recipient1@outlook.com`, `recipient2@outlook.com` and `recipient3@outlook.com`. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": "recipient1@outlook.com"}, {"Name": null, "Address": "recipient2@outlook.com"}, {"Name": null, "Address": "recipient3@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient1@outlook.com"), new EmailAddress("recipient2@outlook.com"), new EmailAddress("recipient3@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient1@outlook.com`, `recipient2@outlook.com` and `recipient3@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with a CC or BCC recipient + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com` with `cc@outlook.com` and `bcc@outlook.com` as the [CC][CC Glossary] and [BCC][BCC Glossary] recipients for the email respectively. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List(){ new EmailAddress("cc@outlook.com") }, bcc: new List(){ new EmailAddress("bcc@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`. Both `cc@outlook.com` and `bcc@outlook.com` will also recieve copies of the email as they are listed as [CC][CC Glossary] and [BCC][BCC Glossary] recipients, and then the session is closed. + +*** + +### Sending an email with multiple CC or BCC recipients + +This example will send an email from `sender@gmail.com` to `recipient@outlook.com` with `cc1@outlook.com` and `cc2@outlook.com` as the [CC][CC Glossary] recipients and `bcc1@outlook.com` and `bcc2@outlook.com` as the [BCC][BCC Glossary] recipients for the email. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be 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": [{"Name": null, "Address": "cc1@outlook.com"}, {"Name": null, "Address": "cc2@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc1@outlook.com"}, {"Name": null, "Address": "bcc2@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List(){ new EmailAddress("cc1@outlook.com"), new EmailAddress("cc2@outlook.com") }, bcc: new List(){ new EmailAddress("bcc1@outlook.com"), new EmailAddress("bcc2@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`. Both `cc1@outlook.com` and `cc2@outlook.com` will also recieve copies of the email as they are listed as [CC][CC Glossary] recipients, and both `bcc1@outlook.com` and `bcc2@outlook.com` will recieve copies of the email as they are listed as [BCC][BCC Glossary] recipients. Finally, the session is closed. + +*** + +### Sending an email with a different priority + +This example will send an email with [Urgent][] priority 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 set to `true` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information on: + +- What priorities an email can be sent as, see [EmailMessagePriority][] +- The effect of changing the [Priority][] of the [Email Message][Email Message Property], see [How does Priority affect sending an email?][] +- 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": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [BodyFormat][] is `null`, the email will be sent with a [Text][] body. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Urgent][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with an HTML body + +This example will send an email with an [HTML][] body 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 set to `true` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information on: + +- What other body formats an email can be sent with, see [EmailMessageBodyFormat][] +- The effect of changing the [BodyFormat][] of the [Email Message][Email Message Property], see [How does BodyFormat affect sending an email?][] +- 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": "EmailMessageBodyFormat.Html", "Body": "

Example email body

", "Attachments": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Html, body: "

Example email body

", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] is `null`, the email will be sent with [Normal][] priority. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and an [HTML][] body of `"

Example email body

"`, and then the session is closed. + +*** + +### Sending an email with a single attachment + +This example will send an email with a single attachment, `attachment.txt`, from `sender@gmail.com` to `recipient@outlook.com`. The attachment is located at `C:\attachment.txt` on the server executing the flow. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be set to `true` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information on: + +- Email attachments, see [Attachments][Attachments Remarks] +- 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": ["C:\\attachment.txt"]}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List(){ @"C:\attachment.txt" })` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.

The [Attachments][Attachments Remarks] are added to the email by providing file paths pointing to the files to be attached to the email. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority containing a text file attachment, `attachment.txt`, is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with multiple attachments + +This example will send an email with mutiple attachments, `attachment1.txt` and `attachment2.txt` from `sender@gmail.com` to `recipient@outlook.com`. The attachments are located at the paths `C:\attachment1.txt` and `C:\attachment2.txt` on the server executing the flow. The example uses the [SMTP][] server hosted at `smtp.gmail.com` on [Port][] `465` which requires [UseSsl][] to be set to `true` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information on: + +- Email attachments, see [Attachments][Attachments Remarks] +- 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": ["C:\\attachment1.txt", "C:\\attachment2.txt"]}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List(){ @"C:\attachment1.txt", @"C:\attachment2.txt" })` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.

The [Attachments][Attachments Remarks] are added to the email by providing file paths pointing to the files to be attached to the email. | +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority containing two text file attachments, `attachment1.txt` and `attachment2.txt`, is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email with UseSsl set to false + +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][] `587` which requires [UseSsl][] to be set to `false` within the [Gmail Session Details][Gmail Session Details Property]. + +For more information on 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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 587, "UseSsl": false}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 587, false), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [Password][] property in the [UserCredentials][] can be 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][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +### Sending an email using OAuth + +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][]. + +The authentication mechanism used in this example is OAuth, the specific authentication flow used is often referred to as "Two-Legged OAuth". Therefore, for this example to work correctly: + +- Credentials provided must be for a [Gmail][] account connected to a Google Workspace +- Credentials in [Gmail Session Details][Gmail Session Details Property] must be a [GmailOAuthCertificateCredentials][] which requires: + - [CertificatePath][] + - [CertificatePassword][] + - [FromAddress][] + - [ClientId][] +- [CertificatePath][] must be a path pointing to a certificate accessible from the server executing the flow + +For more information on: + +- What each of the properties in the [GmailOAuthCertificateCredentials][] needs to be, see [GmailOAuthCertificateCredentials][] +- Using a certificate file, see [Certificate Files][] +- How to set up the Gmail account so that this authentication mechanism can be used, see [Setting up a Gmail account for OAuth authentication][] + +#### 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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Gmail Session Details][Gmail Session Details Property] | `($)GmailSessionDetails` with value `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}}`

In this example `($)GmailSessionDetails` has been set up using the following [Expression][]:

`new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new GmailOAuthCertificateCredentials(@"C:\certificate.p12", "encryptedPassword", "sender@gmail.com", "clientId"))` | `($)GmailSessionDetails` is a variable of type [GmailSessionDetails][]

The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] is a path pointing to a certificate accessible from the server executing the flow.

For information on:
  • What each of the properties in the [GmailOAuthCertificateCredentials][] needs to be, see [GmailOAuthCertificateCredentials][]
  • How to set up the [Gmail][] account so that this authentication mechanism can be used, see [Setting up a Gmail account for OAuth authentication][]
The [CertificatePassword][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` |`($)CloseSession` is a variable of type [Boolean][] | + +#### Result + +An email with [Normal][] priority is sent from `sender@gmail.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the session is closed. + +*** + +## Properties + +### Email Message + +The [Email Message][Email Message Property] to send via the [SMTP][] server hosted by [Gmail][] specified in the [Gmail Session Details][Gmail Session Details Property]. This property contains all of the information in relation to the email to be sent, these are: + +- [To][] +- [From][] +- [Cc][] +- [Bcc][] +- [Priority][] +- [Subject][] +- [BodyFormat][] +- [Body][] +- [Attachments][] + +Note that if the properties [Priority][] and [BodyFormat][] are set to `null` when [creating an EmailMessage using a constructor][], the email will be sent with [Normal][] priority and with a [Text][] body. + +For more detailed information on each of the properties, see [EmailMessage][]. + +||| +|----------|----------| +| Data Type | [EmailMessage][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [EmailMessage][] with value shown below: | + +```json +{ + "To": [ + { + "Name": null, + "Address": "" + } + ], + "From": { + "Name": "", + "Address": "" + }, + "Cc": [], + "Bcc": [], + "Priority": "EmailMessagePriority.Normal", + "Subject": "", + "BodyFormat": "EmailMessageBodyFormat.Text", + "Body": "", + "Attachments": [] +} +``` + +### Gmail Session Details + +The [Gmail Session Details][Gmail Session Details Property] object that includes all of the information required to open and maintain a session with an [SMTP][] server hosted by [Gmail][], including: + +- [ServerDetails][ServerDetails Property] - must be provided in order to connect to an [SMTP][] server. This object contains the properties [Host][], [Port][] and [UseSsl][]. For more information on: + - Supported server address formats, see [Supported formats for ServerDetails.Host][]. + - When [UseSsl][] should be set to `true` or `false`, see [Setting UseSsl][]. +- [Credentials][Credentials Property] - must be provided in order to connect to an [SMTP][] server. This object must be a [UserCredentials][] or a [GmailOAuthCertificateCredentials][] and is used for authentication. For more information on how to configure each of these, see [Setting Credentials][]. + +If the [Close Session][Close Session Property] property is set to `false`, then the session will be kept open and can be used in subsequent Send Email Using Gmail blocks which improves performance, see [Opening Sessions][] for more information. + +For more detailed information on each of the properties, see [GmailSessionDetails][]. + +||| +|----------|----------| +| Data Type | [GmailSessionDetails][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)GmailSessionDetails` with no value | + +### Close Session + +[Close Session][Close Session Property] can be specified to choose whether the session is closed or is kept open for use on subsequent Send Email Using Gmail blocks, this defaults to `false` if left blank, please see [Closing Sessions][Closing Sessions] for more information. + +||| +|-----------------|----------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [ArgumentException][] |Thrown when [BodyFormat][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessageBodyFormat][] values (e.g. `(EmailMessageBodyFormat)10`).| +| |Thrown when [Priority][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessagePriority][] values (e.g. `(EmailMessagePriority)10`).| +| |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] is empty (i.e. `""`), contains only whitespace (i.e. `" "`) or contains the NUL character (i.e. `\0`).| +| [ArgumentNullException][] |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] is `null`.| +| [EmailSessionException][] |Thrown when an invalid [Port][] is provided in the [ServerDetails][] within the [Gmail Session Details][Gmail Session Details Property]. For more information, see [Invalid Port][].| +| |Thrown when an invalid [Host][] is provided in the [ServerDetails][] within the [Gmail Session Details][Gmail Session Details Property]. For more information, see [Invalid Host][].| +| |Thrown when a connection cannot be established; this typically occurs when [UseSsl][] within [Gmail Session Details][Gmail Session Details Property] is set to `false` with a [Port][] which requires it to be set to `true`. For more information, see [SSL Required][]. | +| |Thrown when a connection cannot be established; this typically occurs when [UseSsl][] within [Gmail Session Details][Gmail Session Details Property] is set to `true` with a [Port][] which requires it to be set to `false`. For more information, see [SSL Unsupported][]. | +| |Thrown when the [TLS][]/[SSL][] certificate has expired on the [Host][] or is untrusted or invalid. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when a locally installed anti-virus software replaces the [TLS][]/[SSL][] certificate in order to scan web traffic. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when the [CRL][] (Certificate Revocation List) server for the [TLS][]/[SSL][] certificate is down. For more information, see [SSL Unsupported][]. Note that this exception has the same category and error code as the above row, this is a known limitation, see [EmailSessionErrorCode Limitations][]. | +| |Thrown when the [Username][] and [Password][] in the [UserCredentials][] within [Gmail Session Details][Gmail Session Details Property] is incorrect. For more information, see [Invalid User Credentials][]. | +| |Thrown when an invalid [CertificatePath][] and [CertificatePassword][] combination has been provided in the [GmailOAuthCertificateCredentials][]. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] in the [GmailOAuthCertificateCredentials][] points to an invalid [SSL][] certificate. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] points to a non-existent file. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] points to a folder. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] is longer than the system defined maximum length (typically 32,767). For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] contains only whitespace (i.e. `" "`) or contains the NUL character (i.e. `\0`). For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] contains leading spaces. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][] contains invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`). For more information, see [Invalid SSL Certificate][]. | +| |Thrown when access is denied to the file at the [CertificatePath][] provided in the [GmailOAuthCertificateCredentials][]. For more information, see [Invalid SSL Certificate][]. | +| |Thrown when an invalid [FromAddress][] and [ClientId][] combination has been provided in the [GmailOAuthCertificateCredentials][]. For more information, see [Invalid Gmail Client Credentials][].| +| [FileNotFoundException][] |Thrown when a non-existent file path is provided in [Attachments][] within [Email Message][Email Message Property]. | +| [IOException][] |Thrown when the desired socket is held by another process; re-running the flow typically solves this. | +| |Thrown when a file path within [Attachments][] within the [Email Message][Email Message Property] contains leading spaces.| +| |Thrown when a file path within [Attachments][] within the [Email Message][Email Message Property] contains invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`).| +| [PathTooLongException][] |Thrown when a file path provided in the [Attachments][] within the [Email Message][Email Message Property] exceeds the system-defined maximum length (typically 32,767).| +| [PropertyNullException][] |Thrown when the [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [UserCredentials][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [ServerDetails][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [Host][] in [ServerDetails][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [Email Message][Email Message Property] is `null`. | +| |Thrown when the [To][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [From][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [CertificatePath][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [CertificatePassword][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [FromAddress][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| |Thrown when the [ClientId][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is `null`. | +| [PropertyEmptyException][] |Thrown when the [Host][] in [ServerDetails][] within [Gmail Session Details][Gmail Session Details Property] is empty (i.e. `""`). | +| |Thrown when the [To][] within [Email Message][Email Message Property] is empty (i.e. `[]`). | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is empty (i.e. `""`). | +| |Thrown when the [CertificatePath][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is empty (i.e. `""`). | +| |Thrown when the [CertificatePassword][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is empty (i.e. `""`). | +| |Thrown when the [FromAddress][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is empty (i.e. `""`). | +| |Thrown when the [ClientId][] in the [GmailOAuthCertificateCredentials][] within [Gmail Session Details][Gmail Session Details Property] is empty (i.e. `""`). | +| [PropertyValueOutOfRangeException][] |Thrown when the [Port][] in the [ServerDetails][] within [Gmail Session Details][Gmail Session Details Property] is below `1` or above `65535`. For more information, see [Property Is Invalid][]. | +| [SmtpCommandException][] |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is not of the correct format ([RFC 5321][]).| +| |Thrown when the combined size of all of the attachments in the list of [Attachments][] within the [Email Message][Email Message Property] is greater than the limit specified by the email service provider; for [Gmail][] this is `25 MB`.| +| [UnauthorizedAccessException][] |Thrown when access is denied to a file provided in [Attachments][] within [Email Message][Email Message Property].| +| |Thrown when a file path within the [Attachments][] property within [Email Message][Email Message Property] points to a folder.| + +## Remarks + +### How does Priority affect sending an email? + +An email sent with [Urgent][] or [NonUrgent][] priority will have its priority displayed differently depending on the email client. For example, [Outlook][] displays an email that has an [Urgent][] priority with a red exclamation mark like so: + +{{< figure src="/images/send-email-using-smtp-server-important-email.png" >}} + +For more information on how the priority of an email will be displayed, see the help provided by the respective email client. + +### How does BodyFormat affect sending an email? + +An email sent with an [HTML][] body will have its body displayed as an HTML page instead of as plain text. How the email looks in the email client may differ depending on the email client in use. For example, if the [Email Message][Email Message Property] has its [BodyFormat][] set to [HTML][] and the [Body][] has a value of: + +```json +"

Example header text

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/2024.9/Reference/Blocks/http/_index.md b/content/en/docs/2024.9/Reference/Blocks/http/_index.md new file mode 100644 index 000000000..473bf9830 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/http/execute-http-request/_index.md b/content/en/docs/2024.9/Reference/Blocks/http/execute-http-request/_index.md new file mode 100644 index 000000000..2afeb1c3a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/http/execute-http-request/execute-http-request-block-1.md b/content/en/docs/2024.9/Reference/Blocks/http/execute-http-request/execute-http-request-block-1.md new file mode 100644 index 000000000..be5398111 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Http_ExecuteHttpRequest_ExecuteHttpRequestBlock_1.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"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `null`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`null` | `($)HttpCredentials` is a variable with value `null`

As `($)HttpCredentials` is `null`, no authentication will occur when making the request. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Result + +Executing an [HttpRequest][] with a [Uri][] of `https://test-shop.com/api/items` and a [Verb][] of [GET][] using [HTTP 1.1][HTTP11] results in the variable `($)HttpResponse` being updated to the following: + +```json +{ + "ResponseBody": [ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + } + ], + "ErrorMessage": null, + "Headers": { + "Content-Length": 1024, + "Content-Type": "application/json", + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/json`, the [ResponseBody][] is a [Structure][] containing the data. + +*** + +### Executing a POST request + +This example will send a [POST][] 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.POST", "ContentType": "application/json", "Body": "{'name': 'item 3', 'id': 3}", "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.POST, contentType: "application/json", headers: null, body: "{'name': 'item 3', 'id': 3}", httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `null`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`null` | `($)HttpCredentials` is a variable with value `null`

As `($)HttpCredentials` is `null`, no authentication will occur when making the request. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Result + +Executing an [HttpRequest][] with a [Uri][] of `https://test-shop.com/api/items` and a [Verb][] of [POST][] using [HTTP 1.1][HTTP11] results in the variable `($)HttpResponse` being updated to the following: + +```json +{ + "ResponseBody": [ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + }, + { + "name": "item 3", + "id": 3 + } + ], + "ErrorMessage": null, + "Headers": { + "Content-Length": 1024, + "Content-Type": "application/json", + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note the following: + +- The resource `items` at `https://test-shop.com/api/items` contains `item 3` as shown in the [ResponseBody][] of the [Http Response][Http Response Property] shown above +- As the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/json`, the [ResponseBody][] is a [Structure][] containing the data + +*** + +### Executing a request using Basic authentication + +This example will send a [GET][] request to `https://test-shop.com/api/items` using [HTTP 1.1][HTTP11] using Basic authentication which requires [Http Credentials][Http Credentials Property] to be a [UserCredentials][]. + +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"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"Domain": null, "Username": "username", "Password": "encryptedPassword"}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new UserCredentials(username: "username", password: "encryptedPassword")` | `($)HttpCredentials` is a variable of type [UserCredentials][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Result + +Executing an [HttpRequest][] with a [Uri][] of `https://test-shop.com/api/items` and a [Verb][] of [GET][] using [HTTP 1.1][HTTP11] results in the variable `($)HttpResponse` being updated to the following: + +```json +{ + "ResponseBody": [ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + } + ], + "ErrorMessage": null, + "Headers": { + "Content-Length": 1024, + "Content-Type": "application/json", + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/json`, the [ResponseBody][] is a [Structure][] containing the data. + +*** + +### Executing a request using OAuth password credentials + +This example will send a [GET][] request to `https://test-shop.com/api/items` using [HTTP 1.1][HTTP11] using OAuth authentication with password credentials which requires [Http Credentials][Http Credentials Property] to be an [HttpOAuthPasswordCredentials][]. + +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"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"AccessTokenUri": "https://test-shop.com/api/oauth2/token", "ClientAuthentication": null, "Scope": null, "ResourceOwnerUsername": "username", "ResourceOwnerPassword": "encryptedPassword"}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new HttpOAuthPasswordCredentials(accessTokenUri: "https://test-shop.com/api/oauth2/token", clientAuthentication: null, scope: null, resourceOwnerUsername: "username", resourceOwnerPassword: "encryptedPassword")` | `($)HttpCredentials` is a variable of type [HttpOAuthPasswordCredentials][]

The [ResourceOwnerPassword][ResourceOwnerPassword Password Credentials] property in the [HttpOAuthPasswordCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Result + +Executing an [HttpRequest][] with a [Uri][] of `https://test-shop.com/api/items` and a [Verb][] of [GET][] using [HTTP 1.1][HTTP11] results in the variable `($)HttpResponse` being updated to the following: + +```json +{ + "ResponseBody": [ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + } + ], + "ErrorMessage": null, + "Headers": { + "Content-Length": 1024, + "Content-Type": "application/json", + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/json`, the [ResponseBody][] is a [Structure][] containing the data. + +*** + +### Executing a request using OAuth client credentials + +This example will send a [GET][] request to `https://test-shop.com/api/items` using [HTTP 1.1][HTTP11] using OAuth authentication with client credentials which requires [Http Credentials][Http Credentials Property] to be an [HttpOAuthClientCredentials][]. + +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"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"AccessTokenUri": "https://test-shop.com/api/oauth2/token", "ClientAuthentication": {"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "SendAs": "ClientAuthType.Header"}, "Scope": null}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new HttpOAuthClientCredentials(accessTokenUri: "https://test-shop.com/api/oauth2/token", clientAuthentication: new ClientAuthentication("clientId", "encryptedClientSecret", ClientAuthType.Header), scope: null)` | `($)HttpCredentials` is a variable of type [HttpOAuthClientCredentials][]

The [ClientSecret][] property in [ClientAuthentication][] must be encrypted, for more information on how to encrypt the [ClientSecret][], see [EncryptedText][]. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Result + +Executing an [HttpRequest][] with a [Uri][] of `https://test-shop.com/api/items` and a [Verb][] of [GET][] using [HTTP 1.1][HTTP11] results in the variable `($)HttpResponse` being updated to the following: + +```json +{ + "ResponseBody": [ + { + "name": "item 1", + "id": 1 + }, + { + "name": "item 2", + "id": 2 + } + ], + "ErrorMessage": null, + "Headers": { + "Content-Length": 1024, + "Content-Type": "application/json", + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/json`, the [ResponseBody][] is a [Structure][] containing the data. + +*** + +### Calling another Flow + +Note: This example does not follow the base [Uri][] or [API][] as specified [above][Examples Base]; but instead uses the [Uri][] of the [Cortex API Gateway][]. The [Uri][] to send this HTTP request to has the following form: `https://:8722/api///flows//executions/`. + +
+ +This example will send a [POST][] request to the [Uri][] of a [Flow][] within a [published package][Publish Package] using [HTTP 1.1][HTTP11] and run the [Flow][], using Basic authentication which requires [Http Credentials][Http Credentials Property] to be a [UserCredentials][]. This example is similar in functionality to the [Run Flow][] block. + +
+ +The flow being run is `ExampleFlow`. This flow sets the value of an [Output][] variable `ExampleOutput` to `"I love We Are CORTEX"`. This flow is in a published, non-default package `ExamplePackage`. + +
+ +This example will send this request to `https://server.domain.com:8722/api/default/default/flows/ExampleFlow/executions?packageName=ExamplePackage`, where `server.domain.com` is the FQDN of the server hosting an Innovation install. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Http Request][Http Request Property] | `($)HttpRequest`, with value `{"QueryStringParameters": {"packageName": "ExamplePackage"}, "Verb": "RequestVerb.POST", "ContentType": "application/json", "Body": {}, "Uri": "https://server.domain.com:8722/api/default/default/flows/ExampleFlow/executions", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)HttpRequest` has been set up using the following [Expression][]:

`new HttpRequest(uri: "https://server.domain.com:8722/api/default/default/flows/ExampleFlow/executions", queryParameters: new Dictionary({"packageName","ExamplePackage"}), verb: RequestVerb.POST, contentType: "application/json", headers: null, body: "{}", httpVersion: HttpRequestVersion.HTTP11)` | `($)HttpRequest` is a variable of type [HttpRequest][]

In this example, the `queryParameters` [Advanced][] property is an [IDictionary][IDictionary] with three valid keys, `"packageName"`, `"packageVersion"` and `"async"`. `"packageName"` must be specified as the package of the published flow if it is not the default package.`"packageVersion"` may be included to refer to a specific version of a published package if it is not the default version. `"async"` is by default `"false"`, and if set to `"true"` will cause the flow execution to run asynchronously; similar to the [Run Flow Async][] block. | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"Username": "username", "Password":"encryptedPassword"}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new UserCredentials(username: "username", password: "encryptedPassword")` | `($)HttpCredentials` is a variable of type [UserCredentials][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the [password][Password], see [EncryptedText][]. | +| [Http Response][Http Response Property] | `($)HttpResponse`, with no value | `($)HttpResponse` will be set to the type [HttpResponse][] | + +#### Results + +Executing a [POST][] [HttpRequest][] to `https://server.domain.com:8722/api/default/default/flows/ExampleFlow/executions?packageName=ExamplePackage` results in the variable `($)HttpResponse` being updated to the following: +```json +{ + "ResponseBody": { + "ExampleOutput": "I love We Are CORTEX" + }, + "ErrorMessage": null, + "Headers": { + "Date": "2023-10-04T14:17:40+00:00", + "Server": "Kestrel", + "Cache-Control": "no-store, must-revalidate, no-cache", + "X-Content-Type-Options": "nosniff", + "api-supported-versions": "1.0", + "Content-Length": 36, + "Content-Type": "application/json; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +*** + +## Properties + +### Http Request + +The [Http Request][Http Request Property] to execute using the [Http Credentials][Http Credentials Property]. This property contains all of the information in relation to the request to be sent, these are: + +- [Uri][] +- [QueryParameters][] +- [Verb][] +- [ContentType][] +- [Headers][Headers Request] +- [Body][] +- [HttpVersion][] + +For more detailed information on each of the properties, see [HttpRequest][]. + +||| +|----------|----------| +| Data Type | [HttpRequest][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [HttpRequest][] with value shown below: | + +```json +{ + "Uri": "", + "QueryParameters": null, + "Verb": "RequestVerb.GET", + "ContentType": "application/json", + "Headers": null, + "Body": "", + "HttpVersion": "HttpRequestVersion.HTTP10" +} +``` + +### Http Credentials + +The [Http Credentials][Http Credentials Property] object that includes all of the information required for authentication. Mutliple authentication mechanisms are supported which correspond to specific values/data types: + +- `null`: No authentication +- [UserCredentials][]: Basic authentication +- [HttpOAuthPasswordCredentials][]: OAuth authentication using password credentials +- [HttpOAuthClientCredentials][]: OAuth authentication using client credentials + +Note that when using [HttpOAuthPasswordCredentials][] or [HttpOAuthClientCredentials][] as the [Http Credentials][Http Credentials Property], the Execute Http Request block automatically handles retrieval of access tokens using the following rules: + +- If an access token does not exist, a new access token will be retrieved and used when the block runs. +- If an access token already exists but is expired, a new access token will be retrieved and used when the block runs. +- If an access token already exists and is valid, it will be used when the block runs. + +||| +|----------|----------| +| Data Type | [HttpCredentials][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)HttpCredentials` with no value | + +### Http Response + +The [Http Response][Http Response Property] object which contains the response returned from the server. This property contains all of the information in relation to the response from the server, these are: + +- [ResponseBody][] +- [ErrorMessage][] +- [Headers][Headers Response] +- [StatusCode][] + +Note that if the [Headers][Headers Response] contains a key of `Content-Type` with a value containing `json` or `xml`, the [ResponseBody][] will be set to a [Structure][] containing the data. + +For more detailed information on each of the properties, see [HttpResponse][]. + +||| +|----------|----------| +| Data Type | [HttpResponse][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)HttpResponse` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [HttpAuthorisationException][] | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [ResourceOwnerPassword][ResourceOwnerPassword Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is invalid. | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is invalid. | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is invalid. | +| [InvalidRequestException][] | Thrown when the [Uri][] within [Http Request][Http Request Property] is not in the correct format or contains invalid characters. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is not in the correct format or contains invalid characters. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is not in the correct format or contains invalid characters. | +| | Thrown when the [Verb][] within [Http Request][Http Request Property] is not one of the specified [RequestVerb][] values (e.g. `(RequestVerb)10`). | +| | Thrown when a header key in [Headers][Headers Request] within [Http Request][Http Request Property] is empty (i.e. `""`). | +| | Thrown when a header key in [Headers][Headers Request] within [Http Request][Http Request Property] is restricted. | +| | Thrown when a header key in [Headers][Headers Request] within [Http Request][Http Request Property] is restricted and forbidden. | +| | Thrown when a header value in [Headers][Headers Request] within [Http Request][Http Request Property] could not be assigned to its restricted header key. | +| | Thrown when a header value in [Headers][Headers Request] within [Http Request][Http Request Property] could not be converted to its restricted header key's type. | +| | Thrown when the [Body][] within [Http Request][Http Request Property] is not `null` or empty (i.e. `""`) and [RequestVerb][] is [GET][] or [HEAD][]. | +| | Thrown when the [Body][] within [Http Request][Http Request Property] does not match the [ContentType][]. | +| | Thrown when the [HttpVersion][] within [Http Request][Http Request Property] is not one of the specified [HttpRequestVersion][] values (e.g. `(HttpRequestVersion)20`). | +| [PropertyNullException][] | Thrown when the [Http Request][Http Request Property] is `null`. | +| | Thrown when the [Uri][] within [Http Request][Http Request Property] is `null`. | +| | Thrown when the [Username][] within [UserCredentials][] is `null`. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is `null`. | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is `null`. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientAuthentication][ClientAuthentication Client Credentials] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is `null`. | +| [PropertyEmptyException][] | Thrown when the [Uri][] within [Http Request][Http Request Property] is empty (i.e. `""`). | +| | Thrown when the [Username][] within [UserCredentials][] is empty (i.e. `""`). | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is empty (i.e. `""`). | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | + +## Remarks + +### Known Limitations + +None + +[Examples Base]: {{< ref "#examples" >}} +[Http Request Property]: {{< ref "#http-request" >}} +[Http Credentials Property]: {{< ref "#http-credentials" >}} +[Http Response Property]: {{< ref "#http-response" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} + +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[AccessTokenUri Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.AccessTokenUri" >}} +[ClientAuthentication Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.ClientAuthentication" >}} + +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} +[ResourceOwnerUsername Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.ResourceOwnerUsername" >}} +[ResourceOwnerPassword Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.ResourceOwnerPassword" >}} +[AccessTokenUri Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.AccessTokenUri" >}} + +[ClientAuthentication]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.MainDoc" >}} +[ClientId]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientId" >}} +[ClientSecret]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientSecret" >}} +[SendAs]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.SendAs" >}} + +[HttpRequest]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.MainDoc" >}} +[Uri]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.Uri" >}} +[QueryParameters]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.QueryParameters" >}} +[Verb]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.Verb" >}} +[ContentType]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.ContentType" >}} +[Headers Request]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.Headers" >}} +[Body]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.Body" >}} +[HttpVersion]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpRequest.HttpVersion" >}} + +[RequestVerb]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.MainDoc" >}} +[GET]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.GET" >}} +[POST]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.POST" >}} +[PUT]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.PUT" >}} +[DELETE]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.DELETE" >}} +[PATCH]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.PATCH" >}} +[HEAD]: {{< url path="Cortex.Reference.DataTypes.Http.RequestVerb.HEAD" >}} +[HttpRequestVersion]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.MainDoc" >}} +[HTTP10]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.HTTP10" >}} +[HTTP11]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.HTTP11" >}} + +[HttpResponse]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpResponse.MainDoc" >}} +[ResponseBody]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpResponse.ResponseBody" >}} +[ErrorMessage]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpResponse.ErrorMessage" >}} +[Headers Response]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpResponse.Headers" >}} +[StatusCode]: {{< url path="Cortex.Reference.DataTypes.Http.Rest.HttpResponse.StatusCode" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[HttpAuthorisationException]: {{< url path="Cortex.Reference.Exceptions.Http.HttpAuthorisationException.MainDoc" >}} +[InvalidRequestException]: {{< url path="Cortex.Reference.Exceptions.Http.InvalidRequestException.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" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[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" >}} + +[API]: {{< url path="Cortex.Reference.Glossary.A-E.API" >}} +[Flow]:{{< url path="Cortex.Reference.Glossary.F-J.Flow">}} + +[Cortex API Gateway]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[Publish Package]: {{< url path="Cortex.Guides.Gateway.Settings.Packages.MainDoc" >}} +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc">}} +[Run Flow Async]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/_index.md b/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/_index.md new file mode 100644 index 000000000..3c6227477 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute Soap Request" +linkTitle: "Execute Soap Request" +description: "Blocks related to executing SOAP requests." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/execute-soap-request-block-1.md b/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/execute-soap-request-block-1.md new file mode 100644 index 000000000..beed8aecb --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/http/execute-soap-request/execute-soap-request-block-1.md @@ -0,0 +1,494 @@ +--- +title: "Execute Soap Request" +linkTitle: "Execute Soap Request" +description: "Executes a SOAP request and returns a response." +--- + +{{< figure src="/blocks/Cortex_Blocks_Http_ExecuteSoapRequest_ExecuteSoapRequestBlock_1.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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": "20", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)SoapRequest` has been set up using the following [Expression][]:

`new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "20"), headers: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)SoapRequest` is a variable of type [SoapRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `null`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`null` | `($)HttpCredentials` is a variable with value `null`

As `($)HttpCredentials` is `null`, no authentication will occur when making the request. | +| [Soap Response][Soap Response Property] | `($)SoapResponse`, with no value | `($)SoapResponse` will be set to the type [SoapResponse][] | + +#### Result + +Executing a [Soap Request][Soap Request Property] with a [Uri][] of `https://test-converter.com/xml` using a [Soap11Message][] with an [Action][] of `https://test-converter.com/DegreesToKelvin` results in the variable `($)SoapResponse` being updated to the following: + +```json +{ + "ResponseEnvelope": { + "?xml": { + "@version": "1.0", + "@encoding": "utf-8" + }, + "soap:Envelope": { + "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", + "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", + "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/", + "soap:Body": { + "DegreesToKelvinResponse": { + "@xmlns": "https://test-converter.com/DegreesToKelvin/schema", + "kelvin": "293" + } + } + } + }, + "ErrorMessage": null, + "Headers": { + "Content-Type": "text/xml; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `text/xml; charset=utf-8`, the [ResponseEnvelope][] is a [Structure][] containing the data. + +*** + +### Executing a request using SOAP 1.2 + +This example will send a [Soap Request][Soap Request Property] to `https://test-converter.com/xml` using SOAP 1.2 with no authentication which requires: + +- [SoapMessage][SoapMessage Property] to be a [Soap12Message][] +- [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": {"Envelope": "20", "Version": 12}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)SoapRequest` has been set up using the following [Expression][]:

`new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap12Message("20"), headers: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)SoapRequest` is a variable of type [SoapRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `null`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`null` | `($)HttpCredentials` is a variable with value `null`

As `($)HttpCredentials` is `null`, no authentication will occur when making the request. | +| [Soap Response][Soap Response Property] | `($)SoapResponse`, with no value | `($)SoapResponse` will be set to the type [SoapResponse][] | + +#### Result + +Executing a [Soap Request][Soap Request Property] with a [Uri][] of `https://test-converter.com/xml` using a [Soap12Message][] results in the variable `($)SoapResponse` being updated to the following: + +```json +{ + "ResponseEnvelope": { + "?xml": { + "@version": "1.0", + "@encoding": "utf-8" + }, + "soap12:Envelope": { + "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", + "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", + "@xmlns:soap12": "http://www.w3.org/2003/05/soap-envelope", + "soap12:Body": { + "DegreesToKelvinResponse": { + "@xmlns": "https://test-converter.com/DegreesToKelvin/schema", + "kelvin": "293" + } + } + } + }, + "ErrorMessage": null, + "Headers": { + "Content-Type": "application/soap+xml; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `application/soap+xml; charset=utf-8`, the [ResponseEnvelope][] is a [Structure][] containing the data. + +*** + +### Executing a request using Basic authentication + +This example will send a [Soap Request][Soap Request Property] to `https://test-converter.com/xml` using SOAP 1.1 with Basic authentication which requires: + +- [SoapMessage][SoapMessage Property] to be a [Soap11Message][] +- [Http Credentials][Http Credentials Property] to be a [UserCredentials][] + +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": "20", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)SoapRequest` has been set up using the following [Expression][]:

`new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "20"), headers: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)SoapRequest` is a variable of type [SoapRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"Domain": null, "Username": "username", "Password": "encryptedPassword"}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new UserCredentials(username: "username", password: "encryptedPassword")` | `($)HttpCredentials` is a variable of type [UserCredentials][]

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Soap Response][Soap Response Property] | `($)SoapResponse`, with no value | `($)SoapResponse` will be set to the type [SoapResponse][] | + +#### Result + +Executing a [Soap Request][Soap Request Property] with a [Uri][] of `https://test-converter.com/xml` using a [Soap11Message][] with an [Action][] of `https://test-converter.com/DegreesToKelvin` results in the variable `($)SoapResponse` being updated to the following: + +```json +{ + "ResponseEnvelope": { + "?xml": { + "@version": "1.0", + "@encoding": "utf-8" + }, + "soap:Envelope": { + "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", + "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", + "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/", + "soap:Body": { + "DegreesToKelvinResponse": { + "@xmlns": "https://test-converter.com/DegreesToKelvin/schema", + "kelvin": "293" + } + } + } + }, + "ErrorMessage": null, + "Headers": { + "Content-Type": "text/xml; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `text/xml; charset=utf-8`, the [ResponseEnvelope][] is a [Structure][] containing the data. + +*** + +### Executing a request using OAuth password credentials + +This example will send a [Soap Request][Soap Request Property] to `https://test-converter.com/xml` using SOAP 1.1 with OAuth authentication using password credentials which requires: + +- [SoapMessage][SoapMessage Property] to be a [Soap11Message][] +- [Http Credentials][Http Credentials Property] to be an [HttpOAuthPasswordCredentials][] + +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": "20", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)SoapRequest` has been set up using the following [Expression][]:

`new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "20"), headers: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)SoapRequest` is a variable of type [SoapRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"AccessTokenUri": "https://test-converter.com/oauth2/token", "ClientAuthentication": null, "Scope": null, "ResourceOwnerUsername": "username", "ResourceOwnerPassword": "encryptedPassword"}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new HttpOAuthPasswordCredentials(accessTokenUri: "https://test-converter.com/oauth2/token", clientAuthentication: null, scope: null, resourceOwnerUsername: "username", resourceOwnerPassword: "encryptedPassword")` | `($)HttpCredentials` is a variable of type [HttpOAuthPasswordCredentials][]

The [ResourceOwnerPassword][ResourceOwnerPassword Password Credentials] property in the [HttpOAuthPasswordCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| [Soap Response][Soap Response Property] | `($)SoapResponse`, with no value | `($)SoapResponse` will be set to the type [SoapResponse][] | + +#### Result + +Executing a [Soap Request][Soap Request Property] with a [Uri][] of `https://test-converter.com/xml` using a [Soap11Message][] with an [Action][] of `https://test-converter.com/DegreesToKelvin` results in the variable `($)SoapResponse` being updated to the following: + +```json +{ + "ResponseEnvelope": { + "?xml": { + "@version": "1.0", + "@encoding": "utf-8" + }, + "soap:Envelope": { + "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", + "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", + "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/", + "soap:Body": { + "DegreesToKelvinResponse": { + "@xmlns": "https://test-converter.com/DegreesToKelvin/schema", + "kelvin": "293" + } + } + } + }, + "ErrorMessage": null, + "Headers": { + "Content-Type": "text/xml; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `text/xml; charset=utf-8`, the [ResponseEnvelope][] is a [Structure][] containing the data. + +*** + +### Executing a request using OAuth client credentials + +This example will send a [Soap Request][Soap Request Property] to `https://test-converter.com/xml` using SOAP 1.1 with OAuth authentication using client credentials which requires: + +- [SoapMessage][SoapMessage Property] to be a [Soap11Message][] +- [Http Credentials][Http Credentials Property] to be an [HttpOAuthClientCredentials][] + +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": "20", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}`

In this example `($)SoapRequest` has been set up using the following [Expression][]:

`new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "20"), headers: null, httpVersion: HttpRequestVersion.HTTP11)` | `($)SoapRequest` is a variable of type [SoapRequest][] | +| [Http Credentials][Http Credentials Property] | `($)HttpCredentials`, with value `{"AccessTokenUri": "https://test-converter.com/oauth2/token", "ClientAuthentication": {"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "SendAs": "ClientAuthType.Header"}, "Scope": null}`

In this example, `($)HttpCredentials` has been set up using the following [Expression][]:

`new HttpOAuthClientCredentials(accessTokenUri: "https://test-converter.com/oauth2/token", clientAuthentication: new ClientAuthentication("clientId", "encryptedClientSecret", ClientAuthType.Header), scope: null)` | `($)HttpCredentials` is a variable of type [HttpOAuthClientCredentials][]

The [ClientSecret][] property in [ClientAuthentication][] must be encrypted, for more information on how to encrypt the [ClientSecret][], see [EncryptedText][]. | +| [Soap Response][Soap Response Property] | `($)SoapResponse`, with no value | `($)SoapResponse` will be set to the type [SoapResponse][] | + +#### Result + +Executing a [Soap Request][Soap Request Property] with a [Uri][] of `https://test-converter.com/xml` using a [Soap11Message][] with an [Action][] of `https://test-converter.com/DegreesToKelvin` results in the variable `($)SoapResponse` being updated to the following: + +```json +{ + "ResponseEnvelope": { + "?xml": { + "@version": "1.0", + "@encoding": "utf-8" + }, + "soap:Envelope": { + "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", + "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", + "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/", + "soap:Body": { + "DegreesToKelvinResponse": { + "@xmlns": "https://test-converter.com/DegreesToKelvin/schema", + "kelvin": "293" + } + } + } + }, + "ErrorMessage": null, + "Headers": { + "Content-Type": "text/xml; charset=utf-8" + }, + "StatusCode": "HttpStatusCode.OK (200)" +} +``` + +Note that as the [Headers][Headers Response] contains a key of `Content-Type` with a value of `text/xml; charset=utf-8`, the [ResponseEnvelope][] is a [Structure][] containing the data. + +*** + +## Properties + +### Soap Request + +The [Soap Request][Soap Request Property] to execute using the [Http Credentials][Http Credentials Property]. This property contains all of the information in relation to the request to be sent, these are: + +- [SoapMessage][SoapMessage Property] +- [Uri][] +- [Headers][Headers Request] +- [HttpVersion][] + +SOAP 1.1 and SOAP 1.2 are both supported, which correspond to [SoapMessage][SoapMessage Property] within [SoapRequest][] being a [Soap11Message][] and [Soap12Message][] respectively. + +For more information on: + +- How to use a [Soap11Message][], see [Executing a request using SOAP 1.1][] +- How to use a [Soap12Message][], see [Executing a request using SOAP 1.2][] +- Each of the properties, see [SoapRequest][] + +||| +|----------|----------| +| Data Type | [SoapRequest][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [SoapRequest][] with value shown below: | + +```json +{ + "SoapMessage": { + "Action": "", + "Envelope": "", + "Version": 11 + }, + "Uri": "", + "Headers": null, + "HttpVersion": "HttpRequestVersion.HTTP10" +} +``` + +### Http Credentials + +The [Http Credentials][Http Credentials Property] object that includes all of the information required for authentication. Mutliple authentication mechanisms are supported which correspond to specific values/data types: + +- `null`: No authentication +- [UserCredentials][]: Basic authentication +- [HttpOAuthPasswordCredentials][]: OAuth authentication using password credentials +- [HttpOAuthClientCredentials][]: OAuth authentication using client credentials + +Note that when using [HttpOAuthPasswordCredentials][] or [HttpOAuthClientCredentials][] as the [Http Credentials][Http Credentials Property], the Execute Soap Request block automatically handles retrieval of access tokens using the following rules: + +- If an access token does not exist, a new access token will be retrieved and used when the block runs. +- If an access token already exists but is expired, a new access token will be retrieved and used when the block runs. +- If an access token already exists and is valid, it will be used when the block runs. + +||| +|----------|----------| +| Data Type | [HttpCredentials][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)HttpCredentials` with no value | + +### Soap Response + +The [Soap Response][Soap Response Property] object which contains the response returned from the server. This property contains all of the information in relation to the response from the server, these are: + +- [ResponseEnvelope][] +- [ErrorMessage][] +- [Headers][Headers Response] +- [StatusCode][] + +Note that if the [Headers][Headers Response] contains a key of `Content-Type` with a value containing `json` or `xml`, the [ResponseEnvelope][] will be set to a [Structure][] containing the data. + +For more detailed information on each of the properties, see [SoapResponse][]. + +||| +|----------|----------| +| Data Type | [SoapResponse][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)SoapResponse` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [HttpAuthorisationException][] | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [ResourceOwnerPassword][ResourceOwnerPassword Password Credentials] within [HttpOAuthPasswordCredentials][] is invalid. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is invalid. | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is invalid. | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is invalid. | +| [InvalidRequestException][] | Thrown when the [Uri][] within [Soap Request][Soap Request Property] is not in the correct format or contains invalid characters. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is not in the correct format or contains invalid characters. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is not in the correct format or contains invalid characters. | +| | Thrown when a header key in [Headers][Headers Request] within [Soap Request][Soap Request Property] is empty (i.e. `""`). | +| | Thrown when a header key in [Headers][Headers Request] within [Soap Request][Soap Request Property] is restricted. | +| | Thrown when a header key in [Headers][Headers Request] within [Soap Request][Soap Request Property] is restricted and forbidden. | +| | Thrown when a header value in [Headers][Headers Request] within [Soap Request][Soap Request Property] could not be assigned to its restricted header key. | +| | Thrown when a header value in [Headers][Headers Request] within [Soap Request][Soap Request Property] could not be converted to its restricted header key's type. | +| | Thrown when the [Envelope][] in the [SoapMessage][SoapMessage Property] within [Soap Request][Soap Request Property] is not valid XML. | +| | Thrown when the [HttpVersion][] within [Soap Request][Soap Request Property] is not one of the specified [HttpRequestVersion][] values (e.g. `(HttpRequestVersion)20`). | +| [InvalidResponseException][] | Thrown when the [ResponseEnvelope][] within [Soap Response][Soap Response Property] is not valid XML. | +| [PropertyNullException][] | Thrown when the [Soap Request][Soap Request Property] is `null`. | +| | Thrown when the [Uri][] within [Soap Request][Soap Request Property] is `null`. | +| | Thrown when the [SoapMessage][SoapMessage Property] within [Soap Request][Soap Request Property] is `null`. | +| | Thrown when the [Action][] in the [Soap11Message][] within [Soap Request][Soap Request Property] is `null`. | +| | Thrown when the [Envelope][] in the [SoapMessage][SoapMessage Property] within [Soap Request][Soap Request Property] is `null`. | +| | Thrown when the [Username][] within [UserCredentials][] is `null`. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is `null`. | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is `null`. | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientAuthentication][ClientAuthentication Client Credentials] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is `null`. | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is `null`. | +| [PropertyEmptyException][] | Thrown when the [Uri][] within [Soap Request][Soap Request Property] is empty (i.e. `""`). | +| | Thrown when the [Username][] within [UserCredentials][] is empty (i.e. `""`). | +| | Thrown when the [AccessTokenUri][AccessTokenUri Password Credentials] within [HttpOAuthPasswordCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ResourceOwnerUsername][ResourceOwnerUsername Password Credentials] within [HttpOAuthPasswordCredentials][] is empty (i.e. `""`). | +| | Thrown when the [AccessTokenUri][AccessTokenUri Client Credentials] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ClientId][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | +| | Thrown when the [ClientSecret][] in [ClientAuthentication][] within [HttpOAuthClientCredentials][] is empty (i.e. `""`). | + +## Remarks + +### Known Limitations + +None + +[Soap Request Property]: {{< ref "#soap-request" >}} +[Http Credentials Property]: {{< ref "#http-credentials" >}} +[Soap Response Property]: {{< ref "#soap-response" >}} + +[Executing a request using SOAP 1.1]: {{< ref "#executing-a-request-using-soap-11" >}} +[Executing a request using SOAP 1.2]: {{< ref "#executing-a-request-using-soap-12" >}} + +[SoapRequest]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} +[SoapMessage Property]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapRequest.SoapMessage" >}} +[Uri]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapRequest.Uri" >}} +[Headers Request]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapRequest.Headers" >}} +[HttpVersion]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapRequest.HttpVersion" >}} + +[SoapMessage]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapMessage.MainDoc" >}} +[Envelope]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapMessage.Envelope" >}} + +[Soap11Message]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.Soap11Message.MainDoc" >}} +[Action]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.Soap11Message.Action" >}} + +[Soap12Message]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.Soap12Message.MainDoc" >}} + +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[AccessTokenUri Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.AccessTokenUri" >}} +[ClientAuthentication Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.ClientAuthentication" >}} + +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} +[ResourceOwnerUsername Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.ResourceOwnerUsername" >}} +[ResourceOwnerPassword Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.ResourceOwnerPassword" >}} +[AccessTokenUri Password Credentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.AccessTokenUri" >}} + +[ClientAuthentication]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.MainDoc" >}} +[ClientId]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientId" >}} +[ClientSecret]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientSecret" >}} +[SendAs]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.SendAs" >}} + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[SoapResponse]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapResponse.MainDoc" >}} +[ResponseEnvelope]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapResponse.ResponseEnvelope" >}} +[ErrorMessage]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapResponse.ErrorMessage" >}} +[Headers Response]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapResponse.Headers" >}} +[StatusCode]: {{< url path="Cortex.Reference.DataTypes.Http.Soap.SoapResponse.StatusCode" >}} + +[HttpRequestVersion]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.MainDoc" >}} +[HTTP10]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.HTTP10" >}} +[HTTP11]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.HTTP11" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[HttpAuthorisationException]: {{< url path="Cortex.Reference.Exceptions.Http.HttpAuthorisationException.MainDoc" >}} +[InvalidRequestException]: {{< url path="Cortex.Reference.Exceptions.Http.InvalidRequestException.MainDoc" >}} +[InvalidResponseException]: {{< url path="Cortex.Reference.Exceptions.Http.InvalidResponseException.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" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[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" >}} + +[API]: {{< url path="Cortex.Reference.Glossary.A-E.API" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/json/_index.md b/content/en/docs/2024.9/Reference/Blocks/json/_index.md new file mode 100644 index 000000000..e11d8ce65 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/json/_index.md @@ -0,0 +1,5 @@ +--- +title: "Json" +linkTitle: "Json" +description: "Blocks related to working with Json." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/json/convert-json/_index.md b/content/en/docs/2024.9/Reference/Blocks/json/convert-json/_index.md new file mode 100644 index 000000000..57d24569d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/json/convert-json/_index.md @@ -0,0 +1,5 @@ +--- +title: "Convert Json" +linkTitle: "Convert Json" +description: "Convert json to and from other data types." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/json/convert-json/convert-json-to-object-block.md b/content/en/docs/2024.9/Reference/Blocks/json/convert-json/convert-json-to-object-block.md new file mode 100644 index 000000000..e117a50fd --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/json/convert-json/convert-json-to-object-block.md @@ -0,0 +1,248 @@ +--- +title: "Convert Json To Object" +linkTitle: "Convert Json To Object" +description: "Converts Json to an Object." +--- + +{{< figure src="/blocks/Cortex_Blocks_Json_ConvertJson_ConvertJsonToObjectBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/json/convert-json/convert-object-to-json-block.md b/content/en/docs/2024.9/Reference/Blocks/json/convert-json/convert-object-to-json-block.md new file mode 100644 index 000000000..9cef480ae --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Json_ConvertJson_ConvertObjectToJsonBlock.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/2024.9/Reference/Blocks/logs/_index.md b/content/en/docs/2024.9/Reference/Blocks/logs/_index.md new file mode 100644 index 000000000..e051eb041 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/logs/log-event/_index.md b/content/en/docs/2024.9/Reference/Blocks/logs/log-event/_index.md new file mode 100644 index 000000000..1880a3453 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/logs/log-event/log-event-block.md b/content/en/docs/2024.9/Reference/Blocks/logs/log-event/log-event-block.md new file mode 100644 index 000000000..28f34a733 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/logs/log-event/log-event-block.md @@ -0,0 +1,554 @@ +--- +title: "Log Event" +linkTitle: "Log Event" +description: "Logs an event to the filesystem." +--- + +{{< figure src="/blocks/Cortex_Blocks_Logs_LogEvent_LogEventBlock.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 8-9 14-48,linenostart=1" >}} +{ + "@t": "2024-09-05T08:06:15.0000000Z", + "@mt": "{@Event}", + "Event": { + "Type": "User Provisioning", + "Method": "", + "Duration": { + "StartedAt": "2024-09-05T08:05:32.0000000+00:00", + "EndedAt": "2024-09-05T08:06:12.0000000+00:00", + "InSeconds": 40, + "$type": "Cortex.Core.Logging.Common.EventDurationDetails, Cortex.Core.Logging" + }, + "Details": { + "Process": { + "Provision New User": { + "Stages": { + "$values": [ + { + "Configure Active Directory": { + "Tasks": { + "$values": [ + "Add User to Azure Active Directory", + "Add User to On-Premise Active Directory" + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + { + "Configure Email": { + "$values": [ + "Create Outlook Account", + "Create Default Signature" + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + } + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "Tags": { + "Cortex": { + "Tenant.Name": "default", + "System.Name": "default", + "Package.Name": "PackageName", + "Package.Version": "57b45289-cc81-478c-a176-88d0a6104fb2", + "Flow.Id": "c038b421-c7f0-4793-86ad-7bb81801ab9f", + "Flow.Name": "FlowName", + "Execution.Id": "97a98060-acc2-4d11-bc7b-14989d4cf624", + "Workspace.Id": "cf358365-76d8-4100-b58e-4c023563083f", + "Block.Id": "422c42a2-4402-430b-8c96-8f0818f2b324", + "Block.Name": "LogEventBlock", + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "Custom": { + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.Core.Logging.Common.EventTags, Cortex.Core.Logging" + }, + "Correlation": { + "TraceId": "1fd6e5080a25f26b498816933ed91886", + "SpanId": "88f321981aa42963", + "ParentSpanId": "90e588941f7e20ba", + "$type": "Cortex.Core.Logging.Common.EventCorrelationDetails, Cortex.Core.Logging" + }, + "Platform": { + "Node": { + "Name": "CustomerName.MachineName", + "IpAddressOrFqdn": "192.168.1.1", + "Versions": { + "OperatingSystem": "Microsoft Windows NT 10.0.20348.0", + "DotNet": "6.0", + "ServiceFabric": "10.0.1816.9590", + "NServiceBus": "8.1.6", + "Rabbitmq": "3.10.5", + "Erlang": "Erlang OTP 24.0 (12.0)", + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.String, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.Core.Logging.ServiceFabric.NodeDetails, Cortex.Core.Logging" + }, + "Application": { + "Name": "fabric:/Execution/Services/Engine/32.2.4.24340", + "Type": "Cortex.Innovation.Execution", + "Version": "19.1.2.24340", + "$type": "Cortex.Core.Logging.ServiceFabric.ServiceFabricApplicationDetails, Cortex.Core.Logging" + }, + "Service": { + "Name": "fabric:/Execution/Services/Engine/32.2.4.24340/Blocks/46.0.4.24340", + "Type": "Execution", + "Version": "19.1.2.24340", + "PartitionId": "5bf4dc16-4076-46bf-9d20-31cd6d878736", + "ReplicaOrInstanceId": "133697171066478481", + "$type": "Cortex.Core.Logging.ServiceFabric.ServiceFabricServiceDetails, Cortex.Core.Logging" + }, + "Version": "2024.7", + "$type": "Cortex.Core.Logging.ServiceFabric.PlatformDetails, Cortex.Core.Logging" + }, + "$type": "Cortex.Core.Logging.Common.StructuredEventLog, Cortex.Core.Logging" + }, + "SourceContext": "Cortex.ServiceFabric.Service.Execution.ExecutionService" +} +{{< / 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` | `\appsettings.json` | Execution Service is used to execute published flows in a runtime environment (e.g. Development, UAT, Production) | + +An example of the log settings can be found below (some settings that do not need to be modified have been omitted): + +{{< highlight go "linenos=table,hl_lines=5 11-15,linenostart=1" >}} +{ + "Cortex.Blocks.Logs": { + "Using": [ "Serilog.Sinks.File" ], + "MinimumLevel": { + "Default": "Verbose" + }, + "WriteTo": [ + { + "Name": "File", + "Args": { + "path": "%ProgramData%/Cortex/Logging/LogEventBlock-.json", + "rollingInterval": "Day", + "fileSizeLimitBytes": 50000000, + "rollOnFileSizeLimit": true, + "retainedFileCountLimit": 365 + } + } + ] + } +} +{{< / highlight >}} + +A list of the main log settings (highlighted above) and an accompanying description can be found below: + +| Log Setting | Default Value | Description | +|-------------|---------------|-------------| +| `Default` | `"Verbose"` | The default minimum log level that will be logged.

Possible options are `"Verbose"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Fatal"`.

The order of log levels is `"Verbose"->"Debug"->"Information"->"Warning"->"Error"->"Fatal"`. When setting the default log level, that level and every level to its right will be logged. | +| `path` | `"%ProgramData%/Cortex/Logging/LogEventBlock-.json"` | The location that logs will be written to.

This value supports use of environment variables, as seen in the default value.

If any part of the location does not exist, the logging will attempt to create it.

The file names written will include a date format after the `-` and before `.json` (e.g. `"LogEventBlock-yyyyMMdd.json"` -> `"LogEventBlock-20210921.json"`)

The date format used will be decided by the value specified in `rollingInterval`.

The file name may also include a file count number and is added automatically to make sure file names are unique. This can happen if `rollOnFileSizeLimit` is set to `true` and a log file reaches the size specified in `fileSizeLimitBytes`. It can also happen if the log file is locked by another process, preventing it from being written to. | +| `rollingInterval` | `"Day"` | The time interval at which the logging system will create and start logging to a new log file.

Possible options are `"Infinite"`, `"Year"`, `"Month"`, `"Day"`, `"Hour"`, `"Minute"`.

`Infinite` means that the log files never roll over based on a time interval. | +| `fileSizeLimitBytes` | `50000000` | The maximum file size in bytes that the loggging system will write to. Once this size is exceeded the logging system will create and start logging to a new log file.

`Null` can be used to mean unlimited size.

`rollOnFileSizeLimit` must be set to `true` for this setting to take effect. | +| `rollOnFileSizeLimit` | `true` | Whether the loggging system should start creating a new log file if the current one reaches the maximum file size specified in `fileSizeLimitBytes`.

Possible options are `true` and `false`. | +| `retainedFileCountLimit` | `365` | The maximum number of files to retain on disk. Once this number is reached, the loggging system will start delete the oldest file. | + +Please note that if the appsetting.json file cannot be found for one of the services, the logger will use the same default settings specified above. + +### Anatomy of a Log + +The format of the logs written by this block are the same as the logs written by the rest of the {{% ctx %}} Innovation Services. This is to ensure logging is consistent and done one way within {{% ctx %}}. Hopefully this will make it easier to work with logging, and also make it easier to gain a holistic picture into what has happened to a flow execution throughout its entire lifecycle (i.e. from initial request to returning the response to the caller), rather than just what happens inside of the flow. + +An example log can be found below: + +```json +{ + "@t": "2024-09-05T08:06:15.0000000Z", + "@mt": "{@Event}", + "@l": "Debug", + "Event": { + "Type": "User Provisioning", + "Method": "", + "Duration": { + "StartedAt": "2024-09-05T08:05:32.0000000+00:00", + "EndedAt": "2024-09-05T08:06:12.0000000+00:00", + "InSeconds": 40, + "$type": "Cortex.Core.Logging.Common.EventDurationDetails, Cortex.Core.Logging" + }, + "Details": { + "Process": { + "Provision New User": { + "Stages": { + "$values": [ + { + "Configure Active Directory": { + "Tasks": { + "$values": [ + "Add User to Azure Active Directory", + "Add User to On-Premise Active Directory" + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + { + "Configure Email": { + "$values": [ + "Create Outlook Account", + "Create Default Signature" + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + } + ], + "$type": "System.Collections.Generic.List`1[[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "$type": "Cortex.DataTypes.Dictionaries.Structure, Cortex.Core.DataTypes" + }, + "Tags": { + "Cortex": { + "Tenant.Name": "default", + "System.Name": "default", + "Package.Name": "PackageName", + "Package.Version": "57b45289-cc81-478c-a176-88d0a6104fb2", + "Flow.Id": "c038b421-c7f0-4793-86ad-7bb81801ab9f", + "Flow.Name": "FlowName", + "Execution.Id": "97a98060-acc2-4d11-bc7b-14989d4cf624", + "Workspace.Id": "cf358365-76d8-4100-b58e-4c023563083f", + "Block.Id": "422c42a2-4402-430b-8c96-8f0818f2b324", + "Block.Name": "LogEventBlock", + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "Custom": { + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.Object, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.Core.Logging.Common.EventTags, Cortex.Core.Logging" + }, + "Correlation": { + "TraceId": "1fd6e5080a25f26b498816933ed91886", + "SpanId": "88f321981aa42963", + "ParentSpanId": "90e588941f7e20ba", + "$type": "Cortex.Core.Logging.Common.EventCorrelationDetails, Cortex.Core.Logging" + }, + "Platform": { + "Node": { + "Name": "CustomerName.MachineName", + "IpAddressOrFqdn": "192.168.1.1", + "Versions": { + "OperatingSystem": "Microsoft Windows NT 10.0.20348.0", + "DotNet": "6.0", + "ServiceFabric": "10.0.1816.9590", + "NServiceBus": "8.1.6", + "Rabbitmq": "3.10.5", + "Erlang": "Erlang OTP 24.0 (12.0)", + "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.String, System.Private.CoreLib]], System.Private.CoreLib" + }, + "$type": "Cortex.Core.Logging.ServiceFabric.NodeDetails, Cortex.Core.Logging" + }, + "Application": { + "Name": "fabric:/Execution/Services/Engine/32.2.4.24340", + "Type": "Cortex.Innovation.Execution", + "Version": "19.1.2.24340", + "$type": "Cortex.Core.Logging.ServiceFabric.ServiceFabricApplicationDetails, Cortex.Core.Logging" + }, + "Service": { + "Name": "fabric:/Execution/Services/Engine/32.2.4.24340/Blocks/46.0.4.24340", + "Type": "Execution", + "Version": "19.1.2.24340", + "PartitionId": "5bf4dc16-4076-46bf-9d20-31cd6d878736", + "ReplicaOrInstanceId": "133697171066478481", + "$type": "Cortex.Core.Logging.ServiceFabric.ServiceFabricServiceDetails, Cortex.Core.Logging" + }, + "Version": "2024.7", + "$type": "Cortex.Core.Logging.ServiceFabric.PlatformDetails, Cortex.Core.Logging" + }, + "$type": "Cortex.Core.Logging.Common.StructuredEventLog, Cortex.Core.Logging" + }, + "SourceContext": "Cortex.ServiceFabric.Service.Execution.ExecutionService" +} +``` + +A list of each of the log's properties and an accompanying description can be found below: + +| Log Property | Description | +|------------------------------------------------|---------------------------------------------------------------| +| `@t` | The date and time the log was written. The format is [ISO 8601 Standard][]. | +| `@mt` | The message template for the log. This is set to log the entire Event. | +| `@l` | The level for the log. The value of [Event Severity][EventSeverity Property] is used here. | +| `Event` | The event that was logged. | +| `Event.Type` | The type of event that was logged. This can be used for log analysis and reporting. The value of [Event Type][EventType Property] is used here. | +| `Event.Method` | Not currently used for logs generated by the Log Event block. | +| `Event.Duration` | Contains the date and time the event started at, ended at, and its duration. | +| `Event.Duration.StartedAt` | The date and time the event started. The format is [ISO 8601 Standard][]. The value of [Started At][StartedAt Property] is used here. | +| `Event.Duration.EndedAt` | The date and time the event ended. The format is [ISO 8601 Standard][]. The value of [Ended At][EndedAt Property] is used here. | +| `Event.Duration.InSeconds` | The duration of the event in seconds and is calculated using `Event.Duration.StartedAt` and `Event.Duration.EndedAt` . | +| `Event.Duration.$type` | The .NET data type used to represent the duration data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Details` | Contains the details of the event. The value of [Event Details][EventDetails Property] is written as a child property of this (e.g. in this example `Event.Details.Process`). | +| `Event.Details.$type` | The .NET data type used to represent the event details data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Tags` | Contains tags generated by the {{% ctx %}} platform as well as tags generated by the automation solution running on the {{% ctx %}} platform. | +| `Event.Tags.Cortex` | Contains tags generated by the {{% ctx %}} platform. | +| `Event.Tags.Cortex.Tenant.Name` | The name of the tenant the flow that generated this log belongs to. | +| `Event.Tags.Cortex.System.Name` | The name of the system the flow that generated this log belongs to. | +| `Event.Tags.Cortex.Package.Name` | The name of the package containing the flow that generated this log. | +| `Event.Tags.Cortex.Package.Version` | The version of the package containing the flow that generated this log. | +| `Event.Tags.Cortex.Flow.Id` | The ID of the flow containing the block that generated this log. | +| `Event.Tags.Cortex.Flow.Name` | The name of the flow containing the block that generated this log. | +| `Event.Tags.Cortex.Execution.Id` | The ID of the execution that generated this log. | +| `Event.Tags.Cortex.Workspace.Id` | The ID of the workspace containing the block that generated this log. | +| `Event.Tags.Cortex.Block.Id` | The ID of the block that generated this log. | +| `Event.Tags.Cortex.Block.Name` | The name of the block that generated this log. | +| `Event.Tags.Cortex.$type` | The .NET data type used to represent the {{% ctx %}} tags data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Tags.Custom` | Contains custom tags generated by the automation solution running on the {{% ctx %}} platform. | +| `Event.Tags.Custom.$type` | The .NET data type used to represent the custom tags data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Tags.$type` | The .NET data type used to represent the tags data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Correlation` | Contains details that can be used to correlate related events. E.g. The act of starting a new flow execution may result in multiple {{% ctx %}} Innovation Services processing the event. As a result, each service may write its own logs, and additionally the flow developer may also write out multiple logs during the flow execution. The Correlation details allow all of these logs to easily be correlated back together when performing log analysis and reporting to gain a full picture of everything that happened. | +| `Event.Correlation.TraceId` | ID common to all related logs, so they can be easily correlated together. | +| `Event.Correlation.SpanId` | Unique ID for each log, so tools like [Grafana][] can display a call stack, showing each step that occurred when processing an event. | +| `Event.Correlation.ParentSpanId` | The ID of the step that called this step of processing, so tools like [Grafana][] can display a call stack, showing each step that occurred when processing an event. | +| `Event.Correlation.$type` | The .NET data type used to represent the correlation data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Platform` | Contains the details about the platform in which the log was written. | +| `Event.Platform.Node` | Contains the details about the node in which the log was written. | +| `Event.Platform.Node.Name` | The name of the node in which the log was written. | +| `Event.Platform.Node.IpAddressOrFqdn` | The IP Address or Fully Qualified Domain Name of the node in which the log was written. | +| `Event.Platform.Node.Versions` | Contains the details about the versions of software running on the node in which the log was written. | +| `Event.Platform.Node.Versions.OperatingSystem` | The name and version of the Operating system on the node in which the log was written. | +| `Event.Platform.Node.Versions.DotNet` | The version of .NET used by the node in which the log was written. | +| `Event.Platform.Node.Versions.ServiceFabric` | The version of Service Fabric used by the node in which the log was written. | +| `Event.Platform.Node.Versions.NServiceBus` | The version of NServiceBus used by the node in which the log was written. | +| `Event.Platform.Node.Versions.Rabbitmq` | The version of RabbitMQ used by the node in which the log was written. | +| `Event.Platform.Node.Versions.Erlang` | The version of Erlang used by the node in which the log was written. | +| `Event.Platform.Node.Versions.$type` | The .NET data type used to represent the platform node version data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Platform.Node.$type` | The .NET data type used to represent the platform node data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Platform.Application` | Contains the details of the application in which the log was written. | +| `Event.Platform.Application.Name` | The name of the application in which the log was written. | +| `Event.Platform.Application.Type` | The type of the application in which the log was written. | +| `Event.Platform.Application.Version` | The version of the application type in which the log was written. | +| `Event.Platform.Application.$type` | The .NET data type used to represent the platform application data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Platform.Service` | Contains the details of the service in which the log was written. | +| `Event.Platform.Service.Name` | The name of the service in which the log was written. | +| `Event.Platform.Service.Type` | The type of the service in which the log was written. | +| `Event.Platform.Service.Version` | The version of the service type in which the log was written. | +| `Event.Platform.Service.PartitionId` | The Partition ID of the service in which the log was written. | +| `Event.Platform.Service.ReplicaOrInstanceId` | The Replica or Instance ID of the service in which the log was written. | +| `Event.Platform.Service.$type` | The .NET data type used to represent the service data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.Platform.Version` | The version of {{% ctx %}} that was used to write the log. | +| `Event.Platform.$type` | The .NET data type used to represent the platform data. This can be ignored and is an artefact of the underlying implementation. | +| `Event.$type` | The .NET data type used to represent the event data. This can be ignored and is an artefact of the underlying implementation. | +| `SourceContext` | The .NET data type of the Execution Service. This can be ignored and is an artefact of the underlying implementation. | +### Null or Empty Event Type + +If [Event Type][EventType Property] is left blank, `null`, or empty (i.e. `""`) it will default to `Cortex.Blocks.Logs.LogEvent.LogEventBlock`. + +### Null Event Severity + +If [Event Severity][EventSeverity Property] is left blank or set to `null`, it will default to `EventSeverity.Information`. + +### Null Started At + +If [Started At][StartedAt Property] is left blank or set to `null`, a value of `null` will be logged. + +### Null Ended At + +If [Ended At][EndedAt Property] is left blank or set to `null`, a value of `null` will be logged. + +[EventDetails Property]: {{< ref "#event-details" >}} +[EventType Property]: {{< ref "#event-type" >}} +[EventSeverity Property]: {{< ref "#event-severity" >}} +[StartedAt Property]: {{< ref "#started-at" >}} +[EndedAt Property]: {{< ref "#ended-at" >}} + +[Configuring Logging]: {{< ref "#configuring-logging" >}} +[Anatomy of a Log]: {{< ref "#anatomy-of-a-log" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} + +[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" >}} + +[Grafana]: {{< url path="Grafana.MainDoc" >}} +[ElasticSearch]: {{< url path="ElasticSearch.MainDoc" >}} +[Splunk]: {{< url path="Splunk.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Nullable]: {{< url path="Cortex.Reference.DataTypes.Other.Nullable.MainDoc" >}} +[EventSeverity]: {{< url path="Cortex.Reference.DataTypes.Logs.EventSeverity.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/2024.9/Reference/Blocks/loops/_index.md b/content/en/docs/2024.9/Reference/Blocks/loops/_index.md new file mode 100644 index 000000000..42361b03e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/loops/_index.md @@ -0,0 +1,5 @@ +--- +title: "Loops" +linkTitle: "Loops" +description: "Blocks used to perform looping." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/loops/for-each/_index.md b/content/en/docs/2024.9/Reference/Blocks/loops/for-each/_index.md new file mode 100644 index 000000000..8d9e8c1bd --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/loops/for-each/_index.md @@ -0,0 +1,5 @@ +--- +title: "For Each Loop" +linkTitle: "For Each Loop" +description: "Blocks used to loop through the items in a collection (i.e. Lists, Dictionaries and Structures)." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Blocks/loops/for-each/for-each-loop-block.md b/content/en/docs/2024.9/Reference/Blocks/loops/for-each/for-each-loop-block.md new file mode 100644 index 000000000..882a7bbfe --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/loops/for-each/for-each-loop-block.md @@ -0,0 +1,186 @@ +--- +title: "For Each Loop" +linkTitle: "For Each Loop" +description: "Loops through all items in the specified collection (i.e. Lists, Dictionaries and Structures)." +--- + +{{< figure src="/blocks/Cortex_Blocks_Loops_ForEach_ForEachLoopBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/loops/for/_index.md b/content/en/docs/2024.9/Reference/Blocks/loops/for/_index.md new file mode 100644 index 000000000..98ef5db5a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/loops/for/for-loop-block.md b/content/en/docs/2024.9/Reference/Blocks/loops/for/for-loop-block.md new file mode 100644 index 000000000..8b2f4d4df --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Loops_For_ForLoopBlock.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/2024.9/Reference/Blocks/microsoft365/_index.md b/content/en/docs/2024.9/Reference/Blocks/microsoft365/_index.md new file mode 100644 index 000000000..1b6a801db --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/microsoft365/outlook/_index.md b/content/en/docs/2024.9/Reference/Blocks/microsoft365/outlook/_index.md new file mode 100644 index 000000000..2de0946a1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/microsoft365/outlook/send-email/_index.md b/content/en/docs/2024.9/Reference/Blocks/microsoft365/outlook/send-email/_index.md new file mode 100644 index 000000000..c12558811 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/microsoft365/outlook/send-email/send-email-using-microsoft365-block.md b/content/en/docs/2024.9/Reference/Blocks/microsoft365/outlook/send-email/send-email-using-microsoft365-block.md new file mode 100644 index 000000000..cb700400a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Microsoft365_Outlook_SendEmail_SendEmailUsingMicrosoft365Block.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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Credentials][Credentials Property] | `($)Credentials` with value `{"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "TenantId": "tenantId", ObjectId: "objectId"}`

In this example `($)Credentials` has been set up using the following [Expression][]:

`new Microsoft365OAuthCredentials(clientId: "clientId", clientSecret: "encryptedClientSecret", tenantId: "tenantId", objectId: "objectId")` | `($)Credentials` is a variable of type [Microsoft365OAuthCredentials][]

The [ClientSecret][ClientSecret Client Credentials] property in the [Microsoft365OAuthCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | + +#### Result + +An email with [Normal][] priority is sent from `sender@outlook.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the connection is closed. + +*** + +### Sending an email using certificate 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 certificate credentials. Therefore, for this example to work correctly: + +- [Credentials][Credentials Property] provided must be a [Microsoft365OAuthCertificateCredentials][] +- [CertificatePath][] must be a path pointing to a certificate accessible from the server executing the flow + +For more information on: + +- What each of the properties in the [Microsoft365OAuthCertificateCredentials][] needs to be, see [Microsoft365OAuthCertificateCredentials][] +- 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 certificate 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": []}`

In this example `($)EmailMessage` has been set up using the following [Expression][]:

`new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `($)EmailMessage` is a variable of type [EmailMessage][]

As [Priority][] and [BodyFormat][] are `null`, the email will be sent with a [Text][] body and [Normal][] priority.| +| [Credentials][Credentials Property] | `($)Credentials` with value `{"CertificatePath": "C:\\certificate.pfx", "CertificatePassword": "encryptedPassword", "ClientId": "clientId", "TenantId": "tenantId", "ObjectId": "objectId"}`

In this example `($)Credentials` has been set up using the following [Expression][]:

`new Microsoft365OAuthCertificateCredentials(certificatePath: @"C:\certificate.pfx", certificatePassword: "encryptedPassword", clientId: "clientId", tenantId: "tenantId", objectId: "objectId")` | `($)Credentials` is a variable of type [Microsoft365OAuthCertificateCredentials][]

The [CertificatePassword][] property in the [Microsoft365OAuthCertificateCredentials][] must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | + +#### Result + +An email with [Normal][] priority is sent from `sender@outlook.com` to `recipient@outlook.com` with a subject of `"Example email subject"` and a [Text][] body of `"Example email body"`, and then the connection is closed. + +*** + +## Properties + +### Email Message + +The [Email Message][Email Message Property] to send via the [SMTP][] server hosted by [Outlook][]. This property contains all of the information in relation to the email to be sent, these are: + +- [To][] +- [From][] +- [Cc][] +- [Bcc][] +- [Priority][] +- [Subject][] +- [BodyFormat][] +- [Body][] +- [Attachments][] + +Note that if the properties [Priority][] and [BodyFormat][] are set to `null` when [creating an EmailMessage using a constructor][], the email will be sent with [Normal][] priority and with a [Text][] body. + +For more detailed information on each of the properties, see [EmailMessage][]. + +||| +|----------|----------| +| Data Type | [EmailMessage][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [EmailMessage][] with value shown below: | + +```json +{ + "To": [ + { + "Name": null, + "Address": "" + } + ], + "From": { + "Name": "", + "Address": "" + }, + "Cc": [], + "Bcc": [], + "Priority": "EmailMessagePriority.Normal", + "Subject": "", + "BodyFormat": "EmailMessageBodyFormat.Text", + "Body": "", + "Attachments": [] +} +``` + +### Credentials + +The [Credentials][Credentials Property] object that includes all of the information required to connect to an [SMTP][] server hosted by [Outlook][]. There are two data types that can be used, which depends on the desired OAuth mechanism: + +- [Microsoft365OAuthCredentials][]: Using client credentials. For 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][] +- [Microsoft365OAuthCertificateCredentials][]: Using certificate credentials. For information on: + - What each of the properties in the [Microsoft365OAuthCertificateCredentials][], see [Microsoft365OAuthCertificateCredentials][] + - 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 certificate credentials][] + +Note that the Send Email Using Microsoft 365 block automatically handles retrieval of access tokens using the following rules: + +- If an access token does not exist, a new access token will be retrieved and used when the block runs. +- If an access token already exists but is expired, a new access token will be retrieved and used when the block runs. +- If an access token already exists and is valid, it will be used when the block runs. + +It is recommended to use a [Variable][] for [Credentials][Credentials Property] when it will be used across multiple Send Email Using Microsoft 365 blocks, as using a variable will allow for reuse of the same access token. Using a [Literal][] to set the [Credentials][Credentials Property] will cause the access token to only be used once and a new acccess token will be requested for every Send Email Using Microsoft 365 block. + +||| +|----------|----------| +| Data Type | [Microsoft365Credentials][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Microsoft365OAuthCredentials][] with value shown below: | + +```json +{ + "ClientId": "", + "ClientSecret": "", + "TenantId": "", + "ObjectId": "", +} +``` + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [ArgumentException][] |Thrown when [BodyFormat][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessageBodyFormat][] values (e.g. `(EmailMessageBodyFormat)10`).| +| |Thrown when [Priority][] within the [Email Message][Email Message Property] is not one of the specified [EmailMessagePriority][] values (e.g. `(EmailMessagePriority)10`).| +| [CryptographicException][] | Thrown when an incorrect [CertificatePath][] is provided within [Microsoft365OAuthCertificateCredentials][]. | +| | Thrown when an incorrect [CertificatePassword][] is provided within [Microsoft365OAuthCertificateCredentials][]. | +| [FileNotFoundException][] |Thrown when a non-existent file path is provided in [Attachments][] within [Email Message][Email Message Property]. | +| [IOException][] |Thrown when the desired socket is held by another process; re-running the flow typically solves this. | +| [MsalServiceException][] | Thrown when an invalid [ClientId][ClientId Client Credentials] is provided within [Microsoft365OAuthCredentials][]. | +| | Thrown when an invalid [ClientSecret][ClientSecret Client Credentials] is provided within [Microsoft365OAuthCredentials][]. | +| | Thrown when an invalid [TenantId][TenantId Client Credentials] is provided within [Microsoft365OAuthCredentials][]. | +| | Thrown when an invalid [ClientId][ClientId Certificate Credentials] is provided within [Microsoft365OAuthCertificateCredentials][]. | +| | Thrown when an invalid [TenantId][TenantId Certificate Credentials] is provided within [Microsoft365OAuthCertificateCredentials][]. | +| [PropertyNullException][] |Thrown when the [Email Message][Email Message Property] is `null`. | +| |Thrown when the [To][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [From][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is `null`. | +| |Thrown when the [Credentials][Credentials Property] is `null`. | +| |Thrown when the [ClientId][ClientId Client Credentials] within [Microsoft365OAuthCredentials][] is `null`. | +| |Thrown when the [ClientSecret][ClientSecret Client Credentials] within [Microsoft365OAuthCredentials][] is `null`. | +| |Thrown when the [TenantId][TenantId Client Credentials] within [Microsoft365OAuthCredentials][] is `null`. | +| |Thrown when the [ObjectId][ObjectId Client Credentials] within [Microsoft365OAuthCredentials][] is `null`. | +| |Thrown when the [CertificatePath][] within [Microsoft365OAuthCertificateCredentials][] is `null`. | +| |Thrown when the [CertificatePassword][] within [Microsoft365OAuthCertificateCredentials][] is `null`. | +| |Thrown when the [ClientId][ClientId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is `null`. | +| |Thrown when the [TenantId][TenantId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is `null`. | +| |Thrown when the [ObjectId][ObjectId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is `null`. | +| [PropertyEmptyException][] |Thrown when the [To][] within [Email Message][Email Message Property] is empty (i.e. `[]`). | +| |Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is empty (i.e. `""`). | +| |Thrown when the [ClientId][ClientId Client Credentials] within [Microsoft365OAuthCredentials][] is empty (i.e. `""`). | +| |Thrown when the [ClientSecret][ClientSecret Client Credentials] within [Microsoft365OAuthCredentials][] is empty (i.e. `""`). | +| |Thrown when the [TenantId][TenantId Client Credentials] within [Microsoft365OAuthCredentials][] is empty (i.e. `""`). | +| |Thrown when the [ObjectId][ObjectId Client Credentials] within [Microsoft365OAuthCredentials][] is empty (i.e. `""`). | +| |Thrown when the [CertificatePath][] within [Microsoft365OAuthCertificateCredentials][] is empty (i.e. `""`). | +| |Thrown when the [CertificatePassword][] within [Microsoft365OAuthCertificateCredentials][] is empty (i.e. `""`). | +| |Thrown when the [ClientId][ClientId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is empty (i.e. `""`). | +| |Thrown when the [TenantId][TenantId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is empty (i.e. `""`). | +| |Thrown when the [ObjectId][ObjectId Certificate Credentials] within [Microsoft365OAuthCertificateCredentials][] is empty (i.e. `""`). | +| [ServiceException][] | Thrown when an invalid [ObjectId][ObjectId Client Credentials] is provided within [Microsoft365OAuthCredentials][]. | +| | Thrown when an invalid [ObjectId][ObjectId Certificate Credentials] is provided within [Microsoft365OAuthCertificateCredentials][]. | +| | Thrown when trying to send an email as a user that the client application does not have rights to send as. | +| | Thrown when the [Address][] in an [EmailAddress][] within [Email Message][Email Message Property] is not of the correct format ([RFC 5321][]). | +| [UnauthorizedAccessException][] |Thrown when access is denied to a file provided in [Attachments][] within [Email Message][Email Message Property]. | + +## Remarks + +### Known Limitations + +None + +[Email Message Property]: {{< ref "#email-message" >}} +[Credentials Property]: {{< ref "#credentials" >}} + +[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" >}} + +[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" >}} + +[EmailMessageBodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.MainDoc" >}} +[Text]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.Text" >}} + +[Microsoft365Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials.MainDoc" >}} + +[Microsoft365OAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.MainDoc" >}} +[ClientId Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.ClientId" >}} +[ClientSecret Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.ClientSecret" >}} +[TenantId Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.TenantId" >}} +[ObjectId Client Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.ObjectId" >}} + +[Microsoft365OAuthCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.MainDoc" >}} +[CertificatePath]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.CertificatePath" >}} +[CertificatePassword]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.CertificatePassword" >}} +[ClientId Certificate Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.ClientId" >}} +[TenantId Certificate Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.TenantId" >}} +[ObjectId Certificate Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.ObjectId" >}} + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[CryptographicException]: {{< url path="MSDocs.DotNet.Api.System.Security.Cryptography.CryptographicException.MainDoc" >}} +[FileNotFoundException]: {{< url path="MSDocs.DotNet.Api.System.IO.FileNotFoundException" >}} +[IOException]: {{< url path="MSDocs.DotNet.Api.System.IO.IOException" >}} +[MsalServiceException]: {{< url path="MSDocs.DotNet.Api.Microsoft.Identity.Client.MsalServiceException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ServiceException]: {{< url path="MSDocs.DotNet.Api.Microsoft.Graph.ServiceException.MainDoc" >}} +[UnauthorizedAccessException]: {{< url path="MSDocs.DotNet.Api.System.UnauthorizedAccessException" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[Send Email Using SMTP Server]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.MainDoc" >}} + +[Setting up an Outlook account for OAuth authentication using client credentials]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.Authentication.SettingUpClientCredentialsOutlook" >}} +[Setting up an Outlook account for OAuth authentication using certificate credentials]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.Authentication.SettingUpCertificateCredentialsOutlook" >}} + +[SMTP]: {{< url path="Cortex.Reference.Glossary.P-T.SMTP" >}} +[Outlook]: {{< url path="Cortex.Reference.Glossary.K-O.Outlook" >}} +[RFC 5321]: {{< url path="IETF.Email.RFC5321" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/objects/_index.md b/content/en/docs/2024.9/Reference/Blocks/objects/_index.md new file mode 100644 index 000000000..24753ebe5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/objects/_index.md @@ -0,0 +1,5 @@ +--- +title: "Objects" +linkTitle: "Objects" +description: "Blocks common to all object data types." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/_index.md b/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/_index.md new file mode 100644 index 000000000..b1b72c032 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/_index.md @@ -0,0 +1,5 @@ +--- +title: "Convert Object" +linkTitle: "Convert Object" +description: "Convert an object to other data types." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/convert-object-to-text-block-1.md b/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/convert-object-to-text-block-1.md new file mode 100644 index 000000000..8f487f889 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/objects/convert-object/convert-object-to-text-block-1.md @@ -0,0 +1,250 @@ +--- +title: "Convert Object To Text" +linkTitle: "Convert Object To Text" +description: "Converts an object to text by replacing all `{Property}` format parameters in a specified format template with the Object's corresponding property value." +--- + +{{< figure src="/blocks/Cortex_Blocks_Objects_ConvertObject_ConvertObjectToTextBlock_1.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/objects/copy-object/_index.md b/content/en/docs/2024.9/Reference/Blocks/objects/copy-object/_index.md new file mode 100644 index 000000000..88c2803c9 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/objects/copy-object/copy-object-block-1.md b/content/en/docs/2024.9/Reference/Blocks/objects/copy-object/copy-object-block-1.md new file mode 100644 index 000000000..91ffdbbe6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Objects_CopyObject_CopyObjectBlock_1.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/2024.9/Reference/Blocks/queues/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/_index.md new file mode 100644 index 000000000..d143d831b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/dequeue-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/dequeue-item/_index.md new file mode 100644 index 000000000..1f22e687a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/dequeue-item/dequeue-item-block-2.md b/content/en/docs/2024.9/Reference/Blocks/queues/dequeue-item/dequeue-item-block-2.md new file mode 100644 index 000000000..6ee7cde20 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_DequeueItem_DequeueItemBlock_2.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/2024.9/Reference/Blocks/queues/dequeue-item/dequeue-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/queues/dequeue-item/dequeue-items-block-2.md new file mode 100644 index 000000000..98f344eb2 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_DequeueItem_DequeueItemsBlock_2.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/2024.9/Reference/Blocks/queues/enqueue-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/enqueue-item/_index.md new file mode 100644 index 000000000..a92a80839 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/enqueue-item/enqueue-item-block-2.md b/content/en/docs/2024.9/Reference/Blocks/queues/enqueue-item/enqueue-item-block-2.md new file mode 100644 index 000000000..249156260 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemBlock_2.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/2024.9/Reference/Blocks/queues/enqueue-item/enqueue-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/queues/enqueue-item/enqueue-items-block-2.md new file mode 100644 index 000000000..613571b00 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemsBlock_2.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/2024.9/Reference/Blocks/queues/get-count/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/get-count/_index.md new file mode 100644 index 000000000..2fb3d1df1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/get-count/get-count-of-all-items-block-2.md b/content/en/docs/2024.9/Reference/Blocks/queues/get-count/get-count-of-all-items-block-2.md new file mode 100644 index 000000000..f48cc1785 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_GetCount_GetCountOfAllItemsBlock_2.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/2024.9/Reference/Blocks/queues/peek-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/peek-item/_index.md new file mode 100644 index 000000000..1b7c59da4 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/peek-item/peek-item-block.md b/content/en/docs/2024.9/Reference/Blocks/queues/peek-item/peek-item-block.md new file mode 100644 index 000000000..b1506ce63 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_PeekItem_PeekItemBlock_2.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/2024.9/Reference/Blocks/queues/remove-item/_index.md b/content/en/docs/2024.9/Reference/Blocks/queues/remove-item/_index.md new file mode 100644 index 000000000..0a570cc57 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/queues/remove-item/remove-all-items-block.md b/content/en/docs/2024.9/Reference/Blocks/queues/remove-item/remove-all-items-block.md new file mode 100644 index 000000000..8237c530a --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Queues_RemoveItem_RemoveAllItemsBlock_2.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/2024.9/Reference/Blocks/schedules/_index.md b/content/en/docs/2024.9/Reference/Blocks/schedules/_index.md new file mode 100644 index 000000000..4959fc9ea --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/schedules/wait-for/_index.md b/content/en/docs/2024.9/Reference/Blocks/schedules/wait-for/_index.md new file mode 100644 index 000000000..2ac050e2b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/schedules/wait-for/wait-for-duration-block.md b/content/en/docs/2024.9/Reference/Blocks/schedules/wait-for/wait-for-duration-block.md new file mode 100644 index 000000000..a91a26f8b --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Schedules_WaitFor_WaitForDurationBlock.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`
Months: `0`
Days: `0`
Hours: `0`
Minutes: `0`
Seconds: `0`
Milliseconds: `0`| + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentOutOfRangeException][] | Thrown when any of the values or the sum of components of [Duration][Duration Property] are out of range. | +| [PropertyValueOutOfRangeException][] | Thrown when [Duration][Duration Property] is negative (i.e. the sum of the components of [Duration][Duration Property] is less than `0` milliseconds). | + +## Remarks + +None + +[Duration Property]: {{< ref "#duration" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} + +[ArgumentOutOfRangeException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentOutOfRangeException" >}} + +[PropertyValueOutOfRangeException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyValueOutOfRangeException.MainDoc" >}} + +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.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/2024.9/Reference/Blocks/ssh/_index.md b/content/en/docs/2024.9/Reference/Blocks/ssh/_index.md new file mode 100644 index 000000000..118737e8e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/ssh/_index.md @@ -0,0 +1,5 @@ +--- +title: "Ssh" +linkTitle: "Ssh" +description: "Blocks related to working with SSH." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/_index.md b/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/_index.md new file mode 100644 index 000000000..aece5ec5d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/_index.md @@ -0,0 +1,5 @@ +--- +title: "Execute Ssh Command" +linkTitle: "Execute Ssh Command" +description: "Blocks related to executing SSH commands." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/execute-ssh-command-block.md b/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/execute-ssh-command-block.md new file mode 100644 index 000000000..de8e7b439 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/ssh/execute-ssh-command/execute-ssh-command-block.md @@ -0,0 +1,315 @@ +--- +title: "Execute Ssh Command" +linkTitle: "Execute Ssh Command" +description: "Executes an SSH command on the specified host." +--- + +{{< figure src="/blocks/Cortex_Blocks_Ssh_ExecuteSshCommand_ExecuteSshCommandBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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": ".*[>\|\$\|#]"}`

In this example `($)SshSessionDetails` has been set up using the following [Expression][]:

`new SshSessionDetails("localhost", 22, new UserCredentials("domain", "username", "encryptedPassword"), $@".*[>\|\$\|#]")` | `($)SshSessionDetails` is a variable of type [SshSessionDetails][] | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Configuration Settings][Configuration Settings Property] | `($)ConfigurationSettings`, with no value | `($)ConfigurationSettings` is a variable of type [Dictionary][]<[String][], [EncryptableText][]> | +| [Response][Response Property] | `($)Response`, with no value | `($)Response` will be set to the type [String][] | +| [Ssh Logs][Ssh Logs Property] | `($)SshLogs`, with no value | `($)SshLogs` will be set to the type [SshLogs][] | + +#### Result + +Running the [Command][Command Property] results in the variable `($)Response` being updated to the following: + +```text +Windows IP Configuration + +Ethernet adapter Ethernet 3: + +Connection-specific DNS Suffix. : reddog.microsoft.com +Link-local IPv6 Address. . . . . : fe80::78eb:a051:2b84:e8bd%6 +IPv4 Address. . . . . . . . . . . : 10.3.0.4 +Subnet Mask . . . . . . . . . . . : 255.255.255.0 +Default Gateway . . . . . . . . . : 10.3.0.1 +``` + +It also results in the variable `($)SshLogs` being updated to the following: + +```json +{ + "WelcomeMessage": "Last login: Tue Mar 1 06:50:23 2022 from 10.8.0.224", + "Logs": "[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange.[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange..." +} +``` + +Note that more logs are included in this example, but have been omitted from `($)SshLogs.Logs`. + +*** + +### Execute a Command using SshCertificateCredentials + +This example will execute a [Command][Command Property] on the server with the following details: + +- Host - `"localhost"` +- Port - `22` +- Domain - `"domain"` + +The server can be connected to using a valid certificate. + +#### 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", "CertificatePath": "C:\\Certificate.pfx", "CertificatePassword": "encryptedCertificatePassword"}, "TerminalPrompt": ".*[>\|\$\|#]"}`

In this example `($)SshSessionDetails` has been set up using the following [Expression][]:

`new SshSessionDetails("localhost", 22, new SshCertificateCredentials("domain", "username", @"C\Certificate.pfx", "encryptedCertificatePassword"), $@".*[>\|\$\|#]")` | `($)SshSessionDetails` is a variable of type [SshSessionDetails][] | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Configuration Settings][Configuration Settings Property] | `($)ConfigurationSettings`, with no value | `($)CloseSession` is a variable of type [Dictionary][]<[String][], [EncryptableText][]> | +| [Response][Response Property] | `($)Response`, with no value | `($)Response` will be set to the type [String][] | +| [Ssh Logs][Ssh Logs Property] | `($)SshLogs`, with no value | `($)SshLogs` will be set to the type [SshLogs][] | + +#### Result + +Running the [Command][Command Property] results in the variable `($)Response` being updated to the following: + +```text +Windows IP Configuration + +Ethernet adapter Ethernet 3: + +Connection-specific DNS Suffix. : reddog.microsoft.com +Link-local IPv6 Address. . . . . : fe80::78eb:a051:2b84:e8bd%6 +IPv4 Address. . . . . . . . . . . : 10.3.0.4 +Subnet Mask . . . . . . . . . . . : 255.255.255.0 +Default Gateway . . . . . . . . . : 10.3.0.1 +``` + +It also results in the variable `($)SshLogs` being updated to the following: + +```json +{ + "WelcomeMessage": "Last login: Tue Mar 1 06:50:23 2022 from 10.8.0.224", + "Logs": "[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange.[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange..." +} +``` + +Note that more logs are included in this example, but have been omitted from `($)SshLogs.Logs`. + +*** + +## Properties + +### Command + +The [Command][Command Property] that will be executed on the [Host][SshSessionDetails Host] specified in the [Ssh Session Details][Ssh Session Details Property]. + +||| +|----------|----------| +| Data Type | [EncryptableText][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Ssh Session Details + +The [Ssh Session Details][Ssh Session Details Property] object that includes all of the information required to open and maintain a SSH session. This property contains all of the information in relation to the server the [Command][Command Property] will be executed on, these are: + +- [Host][SshSessionDetails Host] +- [Port][SshSessionDetails Port] +- [Credentials][SshSessionDetails Credentials] +- [TerminalPrompt][SshSessionDetails TerminalPrompt] + +||| +|----------|----------| +| Data Type | [SshSessionDetails][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)SshSessionDetails` with no value | + +### Close Session + +[Close Session][Close Session Property] can be specified to choose whether the session on the [Host][SshSessionDetails Host] is closed or is kept open for use on subsequent Execute Ssh Command blocks, this defaults to `false` if left blank, please see [Closing Sessions][] for more information. + +||| +|----------|----------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +### Configuration Settings + +The [Configuration Settings][Configuration Settings Property] for the SSH connection and execution. + +||| +|----------|----------| +| Data Type | [IDictionary][]<[String][], [dynamic][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][]<[String][], [dynamic][]> with value shown below: | + +```csharp +new Dictionary { + { "TerminalWidth", "200" }, + { "TerminalType", "vt100" }, + { "Timeout", "60" }, + { "EndOfLineCharacters", "\r" }, + { "CancelCommand", "CtrlC" }, +} +``` + +### Response + +The SSH [Response][Response Property] that is returned from the execution of the [Command][Command Property] on the [Host][SshSessionDetails Host] specified in the [Ssh Session Details][Ssh Session Details Property]. + +||| +|----------|----------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Response` with no value | + +### Ssh Logs + +The [Ssh Logs][Ssh Logs Property] that are returned from the execution of the [Command][Command Property] on the host specified in the [Ssh Session Details][Ssh Session Details Property]. This property contains all of the information in relation to the logs returned by the [Command][Command Property], these are: + +- [WelcomeMessage][] +- [TerminalPromptMatch][] +- [Logs][] + +||| +|----------|----------| +| Data Type | [SshLogs][] | +| Property Type | [Output][] | +| Is [Advanced][] | `true` | +| Default Editor | [Variable][] | +| Default Value | `($)SshLogs` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [PropertyNullException][] | Thrown when [Command][Command Property] is `null`. | +|| Thrown when the [Ssh Session Details][Ssh Session Details Property] is `null`. | +|| Thrown when the [Host][SshSessionDetails Host] within the [Ssh Session Details][Ssh Session Details Property] is `null`. | +|| Thrown when the [Credentials][SshSessionDetails Credentials] within the [Ssh Session Details][Ssh Session Details Property] is `null`. | +|| Thrown when using [SshCertificateCredentials][], the CertificatePath in the specified [Credentials][SshSessionDetails Credentials] within the [Ssh Session Details][Ssh Session Details Property] is `null`. | +| [PropertyEmptyException][] | Thrown when the specified [Host][SshSessionDetails Host] within the [Ssh Session Details][Ssh Session Details Property] is empty. | +|| Thrown when the CertificatePath in the specified [Credentials][SshSessionDetails Credentials] within the [Ssh Session Details][Ssh Session Details Property] is empty. | +| [PropertyValueOutOfRangeException][] | Thrown when the specified [Port][SshSessionDetails Port] within the [Ssh Session Details][Ssh Session Details Property] is below 1 or above 65535. | +| [SshClientException][] | Thrown when one or more settings in [Configuration Settings][Configuration Settings Property] are invalid. (includes a dictionary of SettingName: ExceptionMessage from IPWorksSSHSshClientException) | +|| Thrown when the specified [Host][SshSessionDetails Host] within the [Ssh Session Details][Ssh Session Details Property] is invalid. | +|| Thrown when the specified [Port][SshSessionDetails Port] within the [Ssh Session Details][Ssh Session Details Property] is invalid. | +|| Thrown when the server host key has not been accepted. | +|| Thrown when using [UserCredentials][], the specified domain, username or password within [Credentials][SshSessionDetails Credentials] is invalid. | +|| Thrown when using [SshCertificateCredentials][], the specified Domain, Username, CertificatePath or CertificatePassword is invalid. | +|| Thrown when the [Host][SshSessionDetails Host] exits without using [Close Session][Close Session Property], returning the response received up to the point the host exited the session. | +| [SshResponseException][] | Thrown if the specified [TerminalPrompt][SshSessionDetails TerminalPrompt] does not match the terminal prompt on the host causing the execution to timeout or the timeout was too short to allow for data to be received. | +| [RegexMatchTimeoutException][] | Thrown when the execution time of the regular expression pattern-matching exceeds the time-out interval. | +| [RegexParsingFailedException][] | Thrown when [TerminalPrompt][SshSessionDetails TerminalPrompt] within [Ssh Session Details][Ssh Session Details Property] contains invalid regex. | + +## Remarks + +### Opening Sessions + +The Execute Ssh Command block automatically handles creating and opening a session for the specified [Ssh Session Details][Ssh 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. + +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 [Command][Command Property] has been executed. + +For information on how to open a session, please see [Opening Sessions][]. + +### Using the TerminalPromptMatch Within SshLogs to Reach the End of a Prompt + +[SshLogs][] includes a TerminalPromptMatch property that represents any string within the returned logs that matches the TerminalPrompt property within the [SshSessionDetails][]. + +Some prompts within SSH require multiple interactions before reaching the end of the prompt. The TerminalPromptMatch can be used to make decisions or loop within a flow sending further input to the Ssh Command to navigate to the end of the prompt. + +### Known Limitations + +None + +[Command Property]: {{< ref "#command" >}} +[Ssh Session Details Property]: {{< ref "#ssh-session-details" >}} +[Close Session Property]: {{< ref "#close-session" >}} +[Configuration Settings Property]: {{< ref "#configuration-settings" >}} +[Response Property]: {{< ref "#response" >}} +[Ssh Logs Property]: {{< ref "#ssh-logs" >}} + +[Opening Sessions]: {{< ref "#opening-sessions" >}} +[Closing Sessions]: {{< ref "#closing-sessions" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[SshCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCertificateCredentials.MainDoc" >}} + +[SshSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.MainDoc" >}} +[SshSessionDetails Host]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.Host" >}} +[SshSessionDetails Port]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.Port" >}} +[SshSessionDetails Credentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.Credentials" >}} +[SshSessionDetails TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.TerminalPrompt" >}} +[Logs]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshLogs.Logs" >}} +[WelcomeMessage]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshLogs.WelcomeMessage" >}} +[TerminalPromptMatch]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshLogs.TerminalPromptMatch" >}} + +[SshLogs]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshLogs.MainDoc" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.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" >}} +[SshClientException]: {{< url path="Cortex.Reference.Exceptions.Ssh.SshClientException" >}} +[SshResponseException]: {{< url path="Cortex.Reference.Exceptions.Ssh.SshResponseException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.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" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/tasks/_index.md b/content/en/docs/2024.9/Reference/Blocks/tasks/_index.md new file mode 100644 index 000000000..34e7041e1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/tasks/_index.md @@ -0,0 +1,5 @@ +--- +title: "Tasks" +linkTitle: "Tasks" +description: "Blocks related to working with Tasks." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/_index.md b/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/_index.md new file mode 100644 index 000000000..fa369cb34 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/_index.md @@ -0,0 +1,5 @@ +--- +title: "Cancel Task(s)" +linkTitle: "Cancel Task(s)" +description: "Cancel a Task or multiple Tasks." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/cancel-all-tasks-block-2.md b/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/cancel-all-tasks-block-2.md new file mode 100644 index 000000000..1af757797 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/cancel-all-tasks-block-2.md @@ -0,0 +1,171 @@ +--- +title: "Cancel All Tasks" +linkTitle: "Cancel All Tasks" +description: "Cancels all Tasks in a list." +--- + +{{< figure src="/blocks/Cortex_Blocks_Tasks_CancelTask_CancelAllTasksBlock_2.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/tasks/cancel-task/cancel-task-block-1.md b/content/en/docs/2024.9/Reference/Blocks/tasks/cancel-task/cancel-task-block-1.md new file mode 100644 index 000000000..cca4bb9b0 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Tasks_CancelTask_CancelTaskBlock_1.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/2024.9/Reference/Blocks/tasks/wait-for-task/_index.md b/content/en/docs/2024.9/Reference/Blocks/tasks/wait-for-task/_index.md new file mode 100644 index 000000000..0d2464a6d --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/tasks/wait-for-task/wait-for-all-tasks-block-2.md b/content/en/docs/2024.9/Reference/Blocks/tasks/wait-for-task/wait-for-all-tasks-block-2.md new file mode 100644 index 000000000..1b2f5b7e8 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Tasks_WaitForTask_WaitForAllTasksBlock_2.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/2024.9/Reference/Blocks/tasks/wait-for-task/wait-for-task-block-1.md b/content/en/docs/2024.9/Reference/Blocks/tasks/wait-for-task/wait-for-task-block-1.md new file mode 100644 index 000000000..4915bbd8c --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Tasks_WaitForTask_WaitForTaskBlock_1.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/2024.9/Reference/Blocks/telnet/_index.md b/content/en/docs/2024.9/Reference/Blocks/telnet/_index.md new file mode 100644 index 000000000..35cb370dd --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/telnet/execute-telnet-command/_index.md b/content/en/docs/2024.9/Reference/Blocks/telnet/execute-telnet-command/_index.md new file mode 100644 index 000000000..11e33bc25 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/telnet/execute-telnet-command/execute-telnet-command-block.md b/content/en/docs/2024.9/Reference/Blocks/telnet/execute-telnet-command/execute-telnet-command-block.md new file mode 100644 index 000000000..49633fc0f --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Telnet_ExecuteTelnetCommand_ExecuteTelnetCommandBlock.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]?)\$\|>))"}`

In this example `($)TelnetSessionDetails` has been set up using the following [Expression][]:

`new TelnetSessionDetails("localhost", 23, @"(.*(~(.*[\r\n]?)\$\|>))")` | `($)TelnetSessionDetails` is a variable of type [TelnetSessionDetails][] | +| [Close Session][Close Session Property] | `($)CloseSession` with value `true` | `($)CloseSession` is a variable of type [Boolean][] | +| [Configuration Settings][Configuration Settings Property] | `($)ConfigurationSettings`, with no value | `($)ConfigurationSettings` is a variable of type [Dictionary][]<[String][], [EncryptableText][]> | +| [Response][Response Property] | `($)Response`, with no value | `($)Response` will be set to the type [String][] | +| [Telnet Logs][Telnet Logs Property] | `($)TelnetLogs`, with no value | `($)TelnetLogs` will be set to the type [TelnetLogs][] | + +#### Result + +Running the [Command][Command Property] results in the variable `($)Response` being updated to the following: + +```text +Windows IP Configuration + +Ethernet adapter Ethernet 3: + +Connection-specific DNS Suffix. : reddog.microsoft.com +Link-local IPv6 Address. . . . . : fe80::78eb:a051:2b84:e8bd%6 +IPv4 Address. . . . . . . . . . . : 10.3.0.4 +Subnet Mask . . . . . . . . . . . : 255.255.255.0 +Default Gateway . . . . . . . . . : 10.3.0.1 +``` + +It also results in the variable `($)TelnetLogs` being updated to the following: + +```json +{ + "WelcomeMessage": "Welcome to Microsoft Telnet Server.", + "TerminalPromptMatch": "C:/Users/TelnetUser>", + "Logs": "[Info] Connecting to Localhost.\r\n[Info] Connected to LocalHost.\r\n[Info] Welcome message received.\r\n[Info] Command sent.\r\n[Info] Terminal Prompt found.\r\n[Info] Disconnected from Localhost." +} +``` + +Note that more logs are included in this example, but have been omitted from `($)TelnetLogs.Logs`. + +*** + +## Properties + +### Command + +The [Command][Command Property] that will be executed on the [Host][TelnetSessionDetails Host] specified in the [Telnet Session Details][Telnet Session Details Property]. + +||| +|----------|----------| +| Data Type | [EncryptableText][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | `$@""` | + +### Telnet Session Details + +The [Telnet Session Details][Telnet Session Details Property] object that includes all of the information required to open and maintain a Telnet session. This property contains all of the information in relation to the server the [Command][Command Property] will be executed on, these are: + +- [Host][TelnetSessionDetails Host] +- [Port][TelnetSessionDetails Port] +- [TerminalPrompt][TelnetSessionDetails TerminalPrompt] + +||| +|----------|----------| +| Data Type | [TelnetSessionDetails][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)TelnetSessionDetails` with no value | + +### Close Session + +[Close Session][Close Session Property] can be specified to choose whether the session on the [Host][TelnetSessionDetails Host] is closed or is kept open for use on subsequent Execute Telnet Command blocks, this defaults to `false` if left blank, please see [Closing Sessions][] for more information. + +||| +|----------|----------| +| Data Type | [Boolean][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +### Configuration Settings + +The [Configuration Settings][Configuration Settings Property] for the Telnet connection and execution. + +For a full list of configuration settings please see [TelnetConfigurationSettings][]. + +||| +|----------|----------| +| Data Type | [IDictionary][]<[String][], [EncryptableText][]> | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][]<[String][], [EncryptableText][]> with value shown below: | + +```csharp +new Dictionary { + { "Timeout", "60" }, + { "EndOfLineCharacters", "\r\n" }, + { "CancelCommand", "CtrlC" }, +} +``` + +### Response + +The Telnet [Response][Response Property] that is returned from the execution of the [Command][Command Property] on the [Host][TelnetSessionDetails Host] specified in the [Telnet Session Details][Telnet Session Details Property]. + +||| +|----------|----------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Response` with no value | + +### Telnet Logs + +The [Telnet Logs][Telnet Logs Property] that are returned from the execution of the [Command][Command Property] on the host specified in the [Telnet Session Details][Telnet Session Details Property]. This property contains all of the information in relation to the logs returned by the [Command][Command Property], these are: + +- [WelcomeMessage] +- [TerminalPromptMatch] +- [Logs] + +||| +|----------|----------| +| Data Type | [TelnetLogs][] | +| Property Type | [Output][] | +| Is [Advanced][] | `true` | +| Default Editor | [Variable][] | +| Default Value | `($)TelnetLogs` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|--------------------------------------|-------------| +| [PropertyNullException][] | Thrown when [Command][Command Property] is `null`. | +|| Thrown when the [Telnet Session Details][Telnet Session Details Property] is `null`. | +|| Thrown when the [Host][TelnetSessionDetails Host] within the [Telnet Session Details][Telnet Session Details Property] is `null`. | +| [PropertyEmptyException][] | Thrown when the specified [Host][TelnetSessionDetails Host] within the [Telnet Session Details][Telnet Session Details Property] is empty. | +| [PropertyValueOutOfRangeException][] | Thrown when the specified [Port][TelnetSessionDetails Port] within the [Telnet Session Details][Telnet Session Details Property] is below 1 or above 65535. | +| [TelnetClientException][] | Thrown when one or more settings in [Configuration Settings][Configuration Settings Property] are invalid. (includes a dictionary of SettingName: ExceptionMessage from IPWorksTelnetException) | +|| Thrown when the specified [Host][TelnetSessionDetails Host] within the [Telnet Session Details][Telnet Session Details Property] is invalid. | +|| Thrown when the specified [Port][TelnetSessionDetails Port] within the [Telnet Session Details][Telnet Session Details Property] is invalid. | +| [TelnetServerException][] | Thrown when the [Host][TelnetSessionDetails Host] exits without using [Close Session][Close Session Property], returning the response received up to the point the host exited the session. | +| [RegexMatchTimeoutException][] | Thrown when the execution time of the regular expression pattern-matching exceeds the time-out interval. | +| [RegexParsingFailedException][] | Thrown when [TerminalPrompt][TelnetSessionDetails TerminalPrompt] within [Telnet Session Details][Telnet Session Details Property] contains invalid regex. | + +## Remarks + +### Empty Command + +If the [Command][Command Property] is empty, it will act as an enter command on the terminal. + +### Null or Empty Terminal Prompt + +If the [TerminalPrompt] is null or empty then it defaults to `(.*(~(.*[\r\n]?)\$|>))` (Windows and Linux friendly default). + +### Terminal Prompt Match + +The [TerminalPromptMatch] in the [TelnetLogs] will output the exact terminal prompt that was matched by the [TerminalPrompt] regex. + +### Telnet Response + +The response will contain all output after the [Command][Command Property] and before the next terminal prompt. + +Control characters are removed from the response. + +For Windows machines before Windows Server 2019 or Windows 10 (build 1809) using Telnet Server, the returned data comes back in an less usable format. + +### Default Telnet Port + +The default port is 23. + +### Opening Sessions + +The Execute Telnet Command block automatically handles creating and opening a session for the specified [Telnet Session Details][Telnet 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. + +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 [Command][Command Property] has been executed. + +For information on how to open a session, please see [Opening Sessions][]. + +### Inactivity Timeout + +The inactivity timeout specifies the number of seconds after which to timeout. This is reset every time new data is received. + +Timeout must be a positive [Int32] integer and smaller or equal to [Int32.MaxValue][] (`2147483647`), otherwise a [TelnetResponseException] will be thrown. + +The default inactivity timeout is 60 seconds. + +To change the default inactivity timeout, use the `Timeout` [Configuration Settings][Configuration Settings Property] e.g. + +```csharp +new Dictionary +{ + { "Timeout", "10"}, +} +``` + +### Terminal Type + +The default terminal type is set by the [Host]. + +To change the default terminal type, use the `TerminalType` [Configuration Settings][Configuration Settings Property] e.g. + +```csharp +new Dictionary +{ + { "TerminalType", "vt100"}, +} +``` + +### Terminal Window Size + +The default terminal window size is set by the [Host]. + +To change the terminal window size, use the `TerminalWidth` and `TerminalHeight` [Configuration Settings][Configuration Settings Property] e.g. + +```csharp +new Dictionary +{ + { "TerminalWidth", "500"}, + { "TerminalHeight", "50"}, +} +``` + +If `TerminalWidth` is set but not `TerminalHeight`, `TerminalHeight` defaults to 50. + +If `TerminalHeight` is set but not `TerminalWidth`, `TerminalWidth` defaults to 500. + +Depending on the [Host] you are connecting to, the values supported for `TerminalWidth` and `TerminalHeight` may differ. If values provided are invalid the host may return a response stating such. + +`TerminalWidth` and `TerminalHeight` must be positive [Int32] integers and smaller or equal to [Int32.MaxValue][] (`2147483647`), otherwise a [TelnetClientException] will be thrown. + +### End Of Line Characters + +On certain hosts it is required to send one or more characters e.g. `\r` or `\r\n` after each command. End of line characters can be used to achieve this and are automatically appended to the [Command][Command Property]. + +The default end of line characters are `\r\n`, which on most systems will ensure that the [Command][Command Property] is executed. If the default does not work it can be set through the [Configuration Settings][Configuration Settings Property] using the `EndOfLineCharacters` setting e.g. + +```csharp +new Dictionary +{ + { "EndOfLineCharacters", "\r\n"}, +} +``` + +If an invalid value is provided the [Command][Command Property] will not be executed and will timeout after the [Inactivity Timeout][] has been reached. + +### Handling Commands That Return Interactive Prompts + +Some commands can return interactive prompts (e.g. `press enter for more...`). In these cases, you must set the [TerminalPrompt][] within [SessionDetails][Telnet Session Details Property] to match the prompt which requires interaction, as well as the end of response prompt (e.g `press enter for more\.\.\.|(.*(~(.*[\r\n]?)\$|>))`). The [TerminalPromptMatch][] within the [TelnetLogs][] can then be used to determine whether the full response has been returned or not; if not, further commands need to be sent to continue receiving the response. + +### Do, Dont, Will and Wont Options + +Do, Dont, Will and Wont codes allows negotiation between the client and the telnet server of options for the telnet connection. + +They are set as a semicolon separated list in the [Configuration Settings][Configuration Settings Property] with each as a key e.g + +```csharp +new Dictionary +{ + { "Do", "0;1"}, +} +``` + +The above example shows how to enable the [echo option][] and [binary transmission option][]. For a full list of Do, Dont, Will and Wont codes please see [Telnet Options][]. + +### Configuration Settings + +[Configuration Settings][Configuration Settings Property] are in PascalCase (e.g. `CloseStreamAfterTransfer`). + +For a full list of configuration settings please see [TelnetConfigurationSettings][]. + +### Cancel Command + +The cancel command is sent to the [Host][TelnetSessionDetails Host] by {{% ctx %}} when an execution times out so the [Host][TelnetSessionDetails Host] can stop the execution and allow other commands to be executed on that session. + +The default cancel command is `Ctrl-C`. If the default does not work it can be set through the [Configuration Settings][Configuration Settings Property] using the `CancelCommand` setting e.g. + +```csharp + new Dictionary +{ + { "CancelCommand", "CtrlC" }, +} +``` + +The supported cancel commands are: `CtrlA`, `CtrlB`, `CtrlC`,`CtrlD`,`CtrlE`,`CtrlF`,`CtrlG`,`CtrlH`,`CtrlI`,`CtrlJ`,`CtrlK`,`CtrlL`,`CtrlM`,`CtrlN`,`CtrlO`,`CtrlP`,`CtrlQ`,`CtrlR`,`CtrlS`,`CtrlT`,`CtrlU`,`CtrlV`,`CtrlW`,`CtrlX`,`CtrlY`,`CtrlZ`,`Ctrl[`,`Ctrl\`,`Ctrl]`,`Ctrl^`,`Ctrl_`. + +The above commands are also case insensitive and can be in various formats (e.g. `CtrlA` can also be specified as `ctrlA`, `Ctrl-A`, `Ctrl+A`). + +If `CancelCommand` is empty then its not sent to the host. + +### Proxies + +Communication via a proxy can be achieved through the following [Configuration Settings][Configuration Settings Property]: + +- [FirewallType][TelnetFirewallTypes] - The type of proxy to connect through (required). +- [FirewallHost][TelnetFirewallHost] - The name or IP address of the proxy (required). +- [FirewallPort][TelnetFirewallPort] - The TCP port of the proxy (optional). The default depends on the [FirewallType][TelnetFirewallTypes] specified. +- [FirewallUser][TelnetFirewallUser] - The username to use if the proxy requires authentication (optional). +- [FirewallPassword][TelnetFirewallPassword] - The password to use if the proxy requires authentication (optional). + +The below example shows how to connect through a SOCKS5 proxy (`3`) hosted on `FirewallHost.com` and on port `1080`. + +```csharp + new Dictionary + { + { "FirewallHost", "FirewallHost.com" }, + { "FirewallType", "3" }, + { "FirewallPort", "1080" }, +} +``` + +### Known Limitations + +None + +[Command Property]: {{< ref "#command" >}} +[Telnet Session Details Property]: {{< ref "#telnet-session-details" >}} +[Close Session Property]: {{< ref "#close-session" >}} +[Configuration Settings Property]: {{< ref "#configuration-settings" >}} +[Response Property]: {{< ref "#response" >}} +[Telnet Logs Property]: {{< ref "#telnet-logs" >}} + +[Opening Sessions]: {{< ref "#opening-sessions" >}} +[Closing Sessions]: {{< ref "#closing-sessions" >}} +[Configuration Settings]: {{< ref "#configuration-settings" >}} +[Inactivity Timeout]: {{< ref "#inactivity-timeout" >}} +[Terminal Type]: {{< ref "#terminal-type" >}} +[Command]: {{< ref "#configuration-settings" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[TelnetSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.MainDoc" >}} +[TelnetSessionDetails Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[TelnetSessionDetails Port]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Port" >}} +[TelnetSessionDetails TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.TerminalPrompt" >}} +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[Port]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Port" >}} +[Logs]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetLogs.Logs" >}} +[WelcomeMessage]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetLogs.WelcomeMessage" >}} +[TerminalPromptMatch]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetLogs.TerminalPromptMatch" >}} + +[TelnetLogs]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetLogs.MainDoc" >}} + +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int32.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Int32.MaxValue" >}} + +[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" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} +[TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.TerminalPrompt" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[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" >}} + +[Telnet Options]: {{< url path="RFC.Docs.Telnet.Options.MainDoc" >}} +[echo option]: {{< url path="RFC.Docs.Telnet.Options.Echo" >}} +[binary transmission option]: {{< url path="RFC.Docs.Telnet.Options.BinaryTransmission" >}} +[TelnetConfigurationSettings]: {{< url path="IPWorks.TelnetConfigurationSettings" >}} +[TelnetFirewallTypes]: {{< url path="IPWorks.TelnetFirewallTypes" >}} +[TelnetFirewallHost]: {{< url path="IPWorks.TelnetFirewallHost" >}} +[TelnetFirewallPort]: {{< url path="IPWorks.TelnetFirewallPort" >}} +[TelnetFirewallUser]: {{< url path="IPWorks.TelnetFirewallUser" >}} +[TelnetFirewallPassword]: {{< url path="IPWorks.TelnetFirewallPassword" >}} +[TelnetServerException]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetServerException.MainDoc" >}} +[TelnetClientException]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/variables/_index.md b/content/en/docs/2024.9/Reference/Blocks/variables/_index.md new file mode 100644 index 000000000..e9d011dc5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/variables/_index.md @@ -0,0 +1,5 @@ +--- +title: "Variables" +linkTitle: "Variables" +description: "Blocks related to working with Variables." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/_index.md b/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/_index.md new file mode 100644 index 000000000..9c2999ce5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/_index.md @@ -0,0 +1,5 @@ +--- +title: "Set Variable" +linkTitle: "Set Variable" +description: "Blocks that are used to set Variables." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/set-variable-block-1.md b/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/set-variable-block-1.md new file mode 100644 index 000000000..bd0e6ec5f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/variables/set-variable/set-variable-block-1.md @@ -0,0 +1,202 @@ +--- +title: "Set Variable" +linkTitle: "Set Variable" +description: "Sets a Variable to a given Value." +--- + +{{< figure src="/blocks/Cortex_Blocks_Variables_SetVariable_SetVariableBlock_1.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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/2024.9/Reference/Blocks/wireless/_index.md b/content/en/docs/2024.9/Reference/Blocks/wireless/_index.md new file mode 100644 index 000000000..8e014fc7f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/wireless/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wireless" +linkTitle: "Wireless" +description: "Blocks related to moving the execution." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/_index.md b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/_index.md new file mode 100644 index 000000000..c7a90e900 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wireless Receiver" +linkTitle: "Wireless Receiver" +description: "Blocks related to receiving an execution." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/wireless-receiver-block.md b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/wireless-receiver-block.md new file mode 100644 index 000000000..46a69d439 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-receiver/wireless-receiver-block.md @@ -0,0 +1,53 @@ +--- +title: "Wireless Receiver" +linkTitle: "Wireless Receiver" +description: "Receives executions." +--- + +{{< figure src="/blocks/Cortex_Blocks_Wireless_WirelessReceiver_WirelessReceiverBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Wireless.WirelessReceiver.WirelessReceiverBlock)

+ +## Description + +Receives executions from [Wireless Sender][Wireless Sender Block] 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; selection of the [Wireless Receiver][Wireless Receiver Block Property] block in [Wireless Sender][Wireless Sender Block] blocks is done based on description so it should be set to something appropriate and unique. + +## 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 + +### Wireless Block Scope + +The Wireless blocks are scoped to the workspace that they are placed in; as a result, [Wireless Sender][Wireless Sender Block] blocks will only be able to select [Wireless Receiver][Wireless Receiver Block] blocks that are placed in the same workspace as itself. + +### Multiple Wireless Senders with same Wireless Receiver + +Multiple [Wireless Sender][Wireless Sender Block] blocks can send executions to the same [Wireless Receiver][Wireless Receiver Block] block. + +### Multiple Wireless Receivers with same Description + +If there are multiple [Wireless Receiver][Wireless Receiver Block] blocks with the same Description in the same scope, the [Guid][] of those blocks will be shown in the dropdown entries of the [Wireless Receiver Block][Wireless Receiver Block Property] property's [Literal][Literal Editor] editor in the [Wireless Sender][Wireless Sender Block] block. + +### Known Limitations + +None + +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[Literal Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Wireless Sender Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.MainDoc" >}} +[Wireless Receiver Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessReceiver.WirelessReceiver.MainDoc" >}} +[Wireless Receiver Block Property]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.WirelessReceiverProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/_index.md b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/_index.md new file mode 100644 index 000000000..c1bff71f6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wireless Sender" +linkTitle: "Wireless Sender" +description: "Blocks related to sending an execution." +--- diff --git a/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/wireless-sender-block.md b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/wireless-sender-block.md new file mode 100644 index 000000000..dd9389846 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/wireless/wireless-sender/wireless-sender-block.md @@ -0,0 +1,88 @@ +--- +title: "Wireless Sender" +linkTitle: "Wireless Sender" +description: "Sends an execution to a specific block." +--- + +{{< figure src="/blocks/Cortex_Blocks_Wireless_WirelessSender_WirelessSenderBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Wireless.WirelessSender.WirelessSenderBlock)

+ +## Description + +Sends the execution to the specified [Wireless Receiver][Wireless Receiver Block] block. + +## Examples + +### Sending an Execution to a Wireless Receiver + +This example is for a flow containing two [Wireless Receiver][Wireless Receiver Block] blocks with descriptions set to `Receiver 1` and `Receiver 2` as well as a [Wireless Sender][Wireless Sender Block] block with the following properties: + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Wireless Receiver Block][Wireless Receiver Property] | [Wireless Receiver Block][Wireless Receiver Property], with value `Receiver 1` | [Wireless Receiver Block][Wireless Receiver Property] is of type [WirelessReceiverBlockReference][] | + +#### Result + +Once an execution is started and it reaches the [Wireless Sender][Wireless Sender Block] block the execution will jump to the [Wireless Receiver][Wireless Receiver Block] block with description `Receiver 1`. + +## Properties + +### Wireless Receiver Block + +The [Wireless Receiver][Wireless Receiver Block] block that the execution will be sent to. + +The [Literal Editor][] is the only editor available for this property, and it provides the developer a list of all available [Wireless Receiver][Wireless Receiver Block] blocks in the current workspace to choose from. + +| | | +|--------------------|---------------------------| +| Data Type | [WirelessReceiverBlockReference][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][Literal Editor] | +| Default Value | No value (defaults to `null`) | + +## Exceptions + +| Name | Description | +|------|-------------| +| [WirelessReceiverBlockNotFoundException][] | Thrown when the specified [Wireless Receiver][Wireless Receiver Property] block has been deleted. See [Wireless Receiver Block Not Found][WirelessReceiverExceptionBlockNotFound]. | +| | Thrown when [Wireless Receiver][Wireless Receiver Property] block has not been selected. See [Wireless Receiver Property Empty][WirelessReceiverExceptionPropertyEmpty]. | + +## Remarks + +### Wireless Block Scope + +The Wireless blocks are scoped to the workspace that they are placed in; as a result, [Wireless Sender][Wireless Sender Block] blocks will only be able to select [Wireless Receiver][Wireless Receiver Block] blocks that are placed in the same workspace as itself. + +### Multiple Wireless Senders with same Wireless Receiver + +Multiple [Wireless Sender][Wireless Sender Block] blocks can send executions to the same [Wireless Receiver][Wireless Receiver Block] block. + +### Multiple Wireless Receivers with same Description + +If there are multiple [Wireless Receiver][Wireless Receiver Block] blocks with the same Description in the same scope, the [Guid][] of those blocks will be shown in the dropdown entries of the [Literal][Literal Editor] editor of the [Wireless Receiver Block][Wireless Receiver Property] property. + +### Known Limitations + +#### The Wireless Receiver Block Property can only use the Literal Editor + +The Literal Editor is the only editor available for the [Wireless Receiver Block Property][Wireless Receiver Property] + +In future this limitation may be removed. + +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[Wireless Receiver Property]: {{< ref "#wireless-receiver-block" >}} +[Literal Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Wireless Sender Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.MainDoc" >}} +[Wireless Receiver Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessReceiver.WirelessReceiver.MainDoc" >}} +[WirelessReceiverBlockReference]: {{< url path="Cortex.Reference.DataTypes.Wireless.WirelessReceiverBlockReference.MainDoc" >}} +[WirelessReceiverBlockNotFoundException]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.MainDoc" >}} +[WirelessReceiverExceptionBlockNotFound]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.BlockNotFound" >}} +[WirelessReceiverExceptionPropertyEmpty]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.PropertyEmpty" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Blocks/workspaces/_index.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/_index.md new file mode 100644 index 000000000..02d2c9a3d --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/workspaces/end-workspace/_index.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/end-workspace/_index.md new file mode 100644 index 000000000..fa6587356 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/workspaces/end-workspace/end-workspace-block.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/end-workspace/end-workspace-block.md new file mode 100644 index 000000000..32c4249a6 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Workspaces_EndWorkspace_EndWorkspaceBlock.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/2024.9/Reference/Blocks/workspaces/start-workspace/_index.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/start-workspace/_index.md new file mode 100644 index 000000000..8a383367c --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/workspaces/start-workspace/start-workspace-block.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/start-workspace/start-workspace-block.md new file mode 100644 index 000000000..996d8e618 --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Workspaces_StartWorkspace_StartWorkspaceBlock.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/2024.9/Reference/Blocks/workspaces/workspace/_index.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/workspace/_index.md new file mode 100644 index 000000000..09a5c0e9b --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/workspaces/workspace/workspace-block.md b/content/en/docs/2024.9/Reference/Blocks/workspaces/workspace/workspace-block.md new file mode 100644 index 000000000..2ee8ddde1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/workspaces/workspace/workspace-block.md @@ -0,0 +1,79 @@ +--- +title: "Workspace" +linkTitle: "Workspace" +description: "Represents a new workspace." +--- + +{{< figure src="/blocks/Cortex_Blocks_Workspaces_Workspace_WorkspaceBlock.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/2024.9/Reference/Blocks/xml/_index.md b/content/en/docs/2024.9/Reference/Blocks/xml/_index.md new file mode 100644 index 000000000..14b4020e2 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/xml/convert-xml/_index.md b/content/en/docs/2024.9/Reference/Blocks/xml/convert-xml/_index.md new file mode 100644 index 000000000..98cd5d6a2 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md b/content/en/docs/2024.9/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md new file mode 100644 index 000000000..e4d5d08ac --- /dev/null +++ b/content/en/docs/2024.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/Cortex_Blocks_Xml_ConvertXml_ConvertStructureToXmlBlock.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 +@" + innerNodeValue +" +``` + +## Examples + +### Convert a Structure To Xml + +This example will convert the [Structure][Structure Property] below to its [Xml][Xml Property] representation. + +``` json +{ + "node1" : "1", + "node2" : "2", + "node3" : "3" +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Structure][Structure Property] | `($)Structure`, with value `{{ "node1" : "1"}, {"node2" : "2"}, {"node3" : "3"}}` | `($)Structure` is a variable of type [Structure][] | +| [Xml][Xml Property] | `($)Xml`, with no value | `($)Xml` is a variable that will be set to a [String][] value. | + +#### Result + +Converting: + +``` json +{ + "node1" : "1", + "node2" : "2", + "node3" : "3" +} +``` + +to [Xml][Xml Property] results in the variable `($)Xml` being updated to the following: + +``` xml +@" + 1 + 2 + 3 +" +``` + +* The `"Cortex_DataTypes_Dictionaries_Structure"` root node is added as there is no single top-level key. +* The `"node1"` [Key][Keys] is converted into a child node of `"Cortex_DataTypes_Dictionaries_Structure"` with its corresponding [Item][Items] as the value. +* The `"node2"` [Key][Keys] is converted into a child node of `"Cortex_DataTypes_Dictionaries_Structure"` with its corresponding [Item][Items] as the value. +* The `"node3"` [Key][Keys] is converted into a child node of `"Cortex_DataTypes_Dictionaries_Structure"` with its corresponding [Item][Items] as the value. + +*** + +### Convert a Complex Structure to Xml + +This example will convert the [Structure][Structure Property] below to its [Xml][Xml Property] representation. This scenario is unlikely unless [Xml][Xml Property] has been converted to a [Structure][Structure Property] and is being [Round-Tripped][Round Tripping]. + +``` json +{ + "topLevelKey": { + "@topLevelAttribute" : "exampleAttribute", + "innerKey" : { + "@innerNodeAttribute" : "exampleInnerNodeAttribute", + "nestedKey": "nested key text", + "#text": "inner key text" + }, + "id": [ + 1, + 2, + 3 + ], + } +} +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Structure][Structure Property] | `($)Structure`, with value`"{"topLevelNode": {"@topLevelAttribute" : "exampleAttribute", "innerNode" : { "@innerNodeAttribute" : "exampleInnerNodeAttribute", "nestedNode": "nested node text", "#text": "inner node text" }, "id": [ 1, 2, 3 ], } }"` | `($)Structure` is a variable of type [Structure][] | +| [Xml][Xml Property] | `($)Xml`, with no value | `($)Xml` is a variable that will be set to a [String][] value. | + +#### Result + +Converting: + +``` json +{ + "topLevelKey": { + "@topLevelAttribute" : "exampleAttribute", + "innerKey" : { + "@innerNodeAttribute" : "exampleInnerNodeAttribute", + "nestedKey": "nested key text", + "#text": "inner key text" + }, + "id": [ + 1, + 2, + 3 + ], + } +} +``` + +to [Xml][Xml Property] results in the variable `($)Xml` being updated to the following: + +``` xml +@" + + nested key text + inner key text + + 1 + 2 + 3 +" +``` + +* The key `"topLevelKey"` is converted into the `"topLevelKey"` node. +* The key `"@topLevelAttribute"` is converted into the `"topLevelAttribute"` attribute with its corresponding item as the value. +* The key `"innerKey"` is converted into the `"innerKey"` node. +* The key `"@innerNodeAttribute"` is converted into the `"innerNodeAttribute"` attribute with its corresponding item as the value. +* The key `"nestedKey"` is converted into the `"nestedKey"` node with its corresponding item as the value. +* The key `"#text"` is converted into the value of the `"innerKey"` key with its corresponding item as the value. +* The key `"id"` is converted into three `"id"` nodes with each corresponding item as their values. + +*** + +## Properties + +### Structure + +The [Structure][Structure Property] to convert into [Xml][Xml Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Structure][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Structure` with no value | + +### Xml + +The [Xml][Xml Property] that has been converted from the [Structure][Structure Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Xml` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Structure][Structure Property] is `null`. | +| [PropertyEmptyException][] | Thrown when [Structure][Structure Property] does not contain any items. | +| [XmlSerializationException][] | Thrown when [Structure][Structure Property] has a key that is an empty string. | +|| Thrown when the [Structure][Structure Property] includes an invalid xml declaration key (e.g. `"?xml"` can only accept the following attributes: `"@version"`, `"@encoding"` and `"@standalone"`.) or an invalid document type definition key (e.g. `"!DOCTYPE"` can only accept the following attributes: `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"`). | +|| Thrown when the [Structure][Structure Property] includes an xml declaration key (e.g. `"?xml"`) with an attribute that has an invalid [Basic Data Type][Basic Data Types]. (e.g. `Key: "@version", Value: false`, where `"@version"` must be a numeric value). | +|| Thrown when the [Structure][Structure Property] includes a document type definition key (e.g. `"!DOCTYPE"`) that has an attribute with an invalid [Basic Data Type][Basic Data Types]. (e.g. `Key: "@name", Value: 22`, where `"@name"` must be a text value). | +|| Thrown when the [Structure][Structure Property] includes an attribute key with a [Complex Data Type][Complex Data Types] as a value. (e.g. `Key: "@name", Value: new UserCredentials{...}`). | + +## Remarks + +### Attributes + +If a [Node][Xml Nodes] requires an attribute, the attribute is defined by a [Key][Keys] where the key is the attribute name with an `"@"` before it and the [Item][Items] is the attribute data, for example: + +``` json +{ + "node": { + "@attribute": "Attribute Value", + "innernode": "Inner Node Value" + } +} +``` + +The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property]. + +``` xml +@" + Inner Node Value +" +``` + +### Basic Data Types within Attribute Keys + +Attribute keys may only have [Basic Data Types][] as shown in the example below. An [XmlSerializationException][] will be thrown if [Complex Data Type][Complex Data Types] is used as an attribute key. + +``` json +{ + "node": { + "@validAttribute": "Attribute Value", + "@invalidAttribute": new ComplexDataType("Invalid"), + } +} +``` + +### Key Restrictions + +An Xml declaration key (e.g. `"?xml"`) can only accept the following attributes: `"@version"`, `"@encoding"` and `"@standalone"`. + +A document type definition key (e.g. `"!DOCTYPE"`) can only accept the following attributes: `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"`. + +`"$id"`, `"$ref"`, `"$type"`, `"$value"` and `"values"` are reserved words and should not be used as keys. + +### Text Nodes + +If a key contains a structure as its item, the inner keys are converted into [Nodes][Xml Nodes] with their corresponding items as the values. The key `"#text"` is converted into value of its parent node. + +``` json +{ + "node": { + "innerNode": { + "@attrubute": "attributeValue", + "#text": "Inner Node Value" + }, + "#text": "Node Value" + } +} +``` + +The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property]. + +``` xml +@" + + Inner Node Value + + Node Value +" +``` + +### Duplicate Nodes at the Same Level + +If there are multiple duplicate nodes at the same level, they are defined using a [Key][Keys] where the key is the duplicated node name and the [Item][Items] is a list of each of the corresponding duplicate node's values, for example: + +``` json +{ + "node": { + "duplicateNode": ["First Duplicate Node", "Second Duplicate Node"], + "distinctNode": "Distinct Node" + } +} +``` + +The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property]. + +``` xml +@" + + First Duplicate Node + + + Second Duplicate Node + + + Distinct Node + +" +``` + +### Using Non-Alphanumeric Symbols within Node Names + +Any non-alphanumeric symbol (i.e. symbols that are not `"0"` to `"9"`, `"a"` to `"z"`, or `"A"` to `"Z"`) will be converted to their respective Unicode values when used within a [Key][Keys]. For example, `"!"` and `"&"` are both non-alphanumeric symbols and would be converted to `"x0021"` and `"x0026"` respectively. + +For more information on characters and their Unicode values please see [Character Sets][] + +### Round-tripping + +It should be possible to pass the [Xml][Xml Property] created by this block to the [Convert Xml To Structure][] block, and then pass the [Structure][Structure Property] created by the [Convert Xml To Structure][] block back to this block, as long all values within the [Xml][Xml Property] are [Strings][String]; this is called round-tripping. + +### Node + +`""` is added as a root node when the [Structure][Structure Property] has more than one top-level key to ensure that valid [Xml][Xml Property] is produced. + +``` json +{ + "node1" : "1", + "node2" : "2", + "node3" : "3" +} +``` + +The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property]. + +``` xml +@" + 1 + 2 + 3 +" +``` + +[Convert Xml To Structure]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure.MainDoc" >}} + +[Structure Property]: {{< ref "#structure" >}} +[Xml Property]: {{< ref "#xml" >}} +[Round Tripping]: {{< ref "#round-tripping" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[XmlSerializationException]: {{< url path="Cortex.Reference.Exceptions.Xml.XmlSerializationException" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Items]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Items.MainDoc" >}} +[Complex Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.ComplexDataTypes" >}} +[Basic Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.BasicDataTypes" >}} + +[Character Sets]: {{< url path="W3.CharacterSets" >}} +[Xml Nodes]: {{< url path="W3.XmlNodes" >}} + +[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/2024.9/Reference/Blocks/xml/convert-xml/convert-xml-to-structure-block.md b/content/en/docs/2024.9/Reference/Blocks/xml/convert-xml/convert-xml-to-structure-block.md new file mode 100644 index 000000000..13c1f0eae --- /dev/null +++ b/content/en/docs/2024.9/Reference/Blocks/xml/convert-xml/convert-xml-to-structure-block.md @@ -0,0 +1,332 @@ +--- +title: "Convert Xml To Structure" +linkTitle: "Convert Xml To Structure" +description: "Converts Xml to a Structure." +--- + +{{< figure src="/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertXmlToStructureBlock.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(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 +@" + innerNodeValue +" +``` + +will be converted into: + +``` json +"topLevelNode": { + "innerNode" : "innerNodeValue" +} +``` + +## Examples + +### Convert Xml to a Structure + +This example will convert the [Xml][Xml Property] below to its [Structure][Structure Property] representation. + +``` xml +@" + + nested node text + inner node text + + 1 + 2 + 3 +" +``` + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Xml][Xml Property] | `($)Xml`, with value `"nested node textinner node text123"` | `($)Xml` is a variable of type [String][] | +| [Structure][Structure Property] | `($)Structure`, with no value | `($)Structure` is a variable that will be set to a [Structure][] value | + +#### Result + +Converting: + +``` xml +@" + + nested node text + inner node text + + 1 + 2 + 3 +" +``` + + to a [Structure][Structure Property] results in the variable `($)Structure` being updated to the following: + +``` json +{ + "topLevelNode": { + "@topLevelAttribute" : "exampleAttribute", + "innerNode" : { + "@innerNodeAttribute" : "exampleInnerNodeAttribute", + "nestedNode": "nested node text", + "#text": "inner node text" + }, + "id": [ + 1, + 2, + 3 + ], + } +} +``` + +* The node `"topLevelNode"` is converted into the `"topLevelNode"` key. +* The attribute `"topLevelAttribute"` is converted into the `"@topLevelAttribute"` key with its corresponding value as the item. +* The node `"innerNode"` is converted into the `"innerNode"` key. +* The attribute `"innerNodeAttribute"` is converted into the `"@innerNodeAttribute"` key with its corresponding value as the item. +* The node `"nestedNode"` is converted into the `"nestedNode"` key with its corresponding value as the item. +* The value of `"innerNode"` is converted into the `"#text"` key with its corresponding value as the item. +* The three `"id"` nodes are converted into a single `"id"` key with each corresponding value being an entry of the item list. + +*** + +### Convert Round-tripped Xml to a Structure + +This example will convert the [Xml][Xml Property] below to its [Structure][Structure Property] representation. +This example will only occur when a [Structure][Structure Property] is Converted to [Xml][Xml Property] using the [Convert Structure To Xml][] block and is then converted again using this block. This is called [Round-Tripping][]. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Xml][Xml Property] | `($)Xml`, with value `"123"` | `($)Xml` is a variable of type [String][] | +| [Structure][Structure Property] | `($)Structure`, with no value | `($)Structure` is a variable that will be set to a [Structure][] value | + +#### Result + +Converting: + +``` xml +@" + 1 + 2 + 3 +" +``` + +to a [Structure][Structure Property] results in the variable `($)Structure` being updated to the following: + +``` json +{ + "node1" : "1", + "node2" : "2", + "node3" : "3" +} +``` + +* The `"Cortex_DataTypes_Dictionaries_Structure"` root node is removed and the child nodes are all at the root level. +* The `"node1"` [Node][Xml Nodes] is converted into a [Key][Keys] of `"node1"` with its corresponding value as the [Item][Items]. +* The `"node2"` [Node][Xml Nodes] is converted into a [Key][Keys] of `"node2"` with its corresponding value as the [Item][Items]. +* The `"node3"` [Node][Xml Nodes] is converted into a [Key][Keys] of `"node3"` with its corresponding value as the [Item][Items]. + +*** + +## Properties + +### Xml + +The [Xml][Xml Property] to convert into a [Structure][Structure Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Xml` with no value | + +### Structure + +The [Structure][Structure Property] that has been converted from the [Xml][Xml Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Structure][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Structure` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [PropertyNullException][] | Thrown when [Xml][Xml Property] is `null`. | +| [PropertyEmptyException][] | Thrown when [Xml][Xml Property] is empty (i.e. `""`). | +| [XmlSerializationException][] | Thrown when the [Xml][Xml Property] is not valid (i.e the Xml contains an ampersand symbol or is missing a root node). | + +## Remarks + +### Attributes + +If a [Node][Xml Nodes] has an attribute, the attribute is converted to a [Key][Keys] where the key is the attribute name with an `"@"` before it and the value is the attribute data, for example: + +``` xml +@" + Inner Node Value +" +``` + +The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property] + +``` json +{ + "node": { + "@attribute": "Attribute Value", + "innernode": "Inner Node Value" + } +} +``` + +### Text Nodes + +If a node contains a value and inner nodes or attributes, the inner nodes and attributes are converted into [Keys][] with their corresponding values as the [Items][]. The value of the node is converted into the `"#text"` key with its value as the item. + +``` xml +@" + + Inner Node Value + + Node Value +" +``` + +The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property]. + +``` json +{ + "node": { + "innerNode": { + "@attrubute": "attributeValue", + "#text": "Inner Node Value" + }, + "#text": "Node Value" + } +} +``` + +### Duplicate Nodes at the Same Level + +If a node contains duplicate nodes at the same level, they are converted into a [Key][Keys] where the key is the duplicated node name and the [Item][Items] is a list of each of the corresponding duplicate node's values, for example: + +``` xml +@" + + First Duplicate Node + + + Second Duplicate Node + + + Distinct Node + +" +``` + +The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property]. + +``` json +{ + "node": { + "duplicateNode": ["First Duplicate Node", "Second Duplicate Node"], + "distinctNode": "Distinct Node" + } +} +``` + +### Using Non-Alphanumeric Symbols within Node Names + +Any non-alphanumeric symbol (i.e. symbols that are not `"0"` to `"9"`, `"a"` to `"z"`, or `"A"` to `"Z"`) will be converted to their respective Unicode values when used within a node name. For example, `"!"` and `"&"` are both non-alphanumeric symbols and would be converted to `"x0021"` and `"x0026"` respectively. + +For more information on characters and their Unicode values please see [Character Sets][] + +### Round-tripping + +It should be possible to pass the [Structure][Structure Property] created by this block to the [Convert Structure To Xml][] block, and then pass the [Xml][Xml Property] created by the [Convert Structure To Xml][] block back to this block, as long all values within the [Xml][Xml Property] are [Strings][String]; this is called round-tripping. + +### Node + +The [Convert Structure To Xml][] adds `""` as a root node when the structure has more than one top-level key to ensure that valid [Xml][Xml Property] is produced. + +When the `""` root node is converted from [Xml][Xml Property] to a [Structure][Structure Property] the root node is removed and any inner nodes become the top-level keys. + +``` xml +@" + 1 + 2 + 3 +" +``` + +The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property]. + +``` json +{ + "node1" : "1", + "node2" : "2", + "node3" : "3" +} +``` + +This example will only occur when a [Structure][Structure Property] is Converted to [Xml][Xml Property] and is then converted again using this block. This is called [Round-Tripping][]. + +[Convert Structure To Xml]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml.MainDoc" >}} + +[Structure Property]: {{< ref "#structure" >}} +[Xml Property]: {{< ref "#xml" >}} +[Round-Tripping]: {{< ref "#round-tripping" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[XmlSerializationException]: {{< url path="Cortex.Reference.Exceptions.Xml.XmlSerializationException" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Keys]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Keys.MainDoc" >}} +[Items]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Items.MainDoc" >}} + +[Character Sets]: {{< url path="W3.CharacterSets" >}} +[Xml Nodes]: {{< url path="W3.XmlNodes" >}} + +[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/2024.9/Reference/Concepts/_index.md b/content/en/docs/2024.9/Reference/Concepts/_index.md new file mode 100644 index 000000000..2319ae720 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/_index.md @@ -0,0 +1,8 @@ +--- +title: "Concepts" +linkTitle: "Concepts" +description: "This section includes all reference documentation for concepts required to use {{% ctx %}} Innovation." +weight: 1 +--- + + diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/_index.md new file mode 100644 index 000000000..81a046242 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/_index.md @@ -0,0 +1,6 @@ +--- +title: "Fundamentals" +linkTitle: "Fundamentals" +description: "Fundamental concepts when working with {{% ctx %}} Innovation." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/_index.md new file mode 100644 index 000000000..40a8f4526 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/_index.md @@ -0,0 +1,6 @@ +--- +title: "Blocks" +linkTitle: "Blocks" +description: "Information regarding what a block is, block properties and their editors, and handling exceptions thrown by a block." +weight: 200 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/_index.md new file mode 100644 index 000000000..deaf058a3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/_index.md @@ -0,0 +1,6 @@ +--- +title: "Block Properties" +linkTitle: "Block Properties" +description: "Information regarding what a block property is, the types of properties, the different property editors, and block properties that are common or advanced." +weight: 100 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/advanced-properties.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/advanced-properties.md new file mode 100644 index 000000000..5df1e7238 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/advanced-properties.md @@ -0,0 +1,71 @@ +--- +title: "Advanced Properties" +linkTitle: "Advanced Properties" +description: "Information regarding properties that do not normally need to be configured but allow for more advanced scenarios." +weight: 300 +--- + +# {{% param title %}} + +## Summary + +Some [blocks][All Blocks] have advanced properties that do not normally need to be configured but allow for more advanced scenarios (e.g. A block to send emails would have advanced properties for specifying things like cc, bcc, attachments etc.). Advanced properties may have explicit default values or will be initialised with values that allow the [block][] to run without configuration. + +All advanced properties are hidden by default and can be shown by [Toggling Advanced Properties][], their values will be used in the [block's][block] execution regardless of whether they are hidden or shown. + +## Toggling Advanced Properties + +All advanced properties can be shown or hidden using the Show/Hide Advanced Properties button found on the top right of the [Property Editor][]. This button is used to toggle whether properties are shown or hidden. + +{{< figure src="/images/set-variable/set-variable-block-timeout.svg" >}} + +## Finding Advanced Properties + +A property is defined as advanced within the documentation of a [Block][All Blocks] or [Data Type][]. + +Information regarding which properties are advanced for a [Block][All Blocks] can be found in the "Properties" section. The table within each property in the relevant documentation will have an "Is Advanced" row stating whether the property is advanced or not. + +Information regarding which properties are advanced for a [Data Type][] can be found in the "Remarks" section under "Advanced Properties" in the relevant documentation for that [Data Type][]. + +## Remarks + +### Known Limitations + +#### Toggling advanced properties is not persisted between blocks + +Currently, when advanced properties are shown when editing a [block][] the advanced toggle state is not persisted when switching between [blocks][block]. + +In future this limitation may be removed. + +#### Toggling advanced properties shows or hides all advanced properties + +Currently, it is not possible to show or hide individual advanced properties. + +In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Blocks][] +- [Block Properties][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Toggling Advanced Properties]: {{< ref "#toggling-advanced-properties" >}} + +[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 Editor]: {{< url path="Cortex.Guides.Studio.EastPanel.PropertyEditor" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Data Type]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md new file mode 100644 index 000000000..1b4dcf3a8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/common-properties.md @@ -0,0 +1,154 @@ +--- +title: "Common Properties" +linkTitle: "Common Properties" +description: "Information regarding properties that are common to all or most blocks." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +There are a number of properties that are common across all or most [blocks][All Blocks]. + +These properties include: + +- [Description Property][] +- [Semaphore Property][] +- [Run As Property][] +- [Block Timeout Property][] + +## Description Property + +The Description property is available on all [blocks][All Blocks]. It defaults to the name of the block and can be used to describe the action or function the block is performing. Any text entered in the Description property is displayed next to the [block's][block] icon on the [workspace][]. + +{{< figure src="/images/set-variable/set-variable-description.svg" >}} + +## Semaphore Property + +The Semaphore property is an [advanced property][Advanced Properties] available on most [blocks][All Blocks]. It is used to restrict the number of [executions][] that can execute the [block][WhatIsBlock] at any one time. + +The default value of `null` indicates that there is no [semaphore][]. + +The Semaphore property has the following sub-properties: + +- [Scope][SemaphoreScope], which defaults to: + - [Tenant][]: `ScopeOption.Current`. + - [System][]: `ScopeOption.Current`. + - [Package][]: `ScopeOption.Current`. + - [Flow][]: `ScopeOption.All`. +- [Name][SemaphoreName], which defaults to an empty string (i.e. `""`). +- [ConcurrencyLimit][SemaphoreConcurrencyLimit], which defaults to 0. +- [Queue][SemaphoreQueue], which defaults to `null`. + - [Priority][QueuePriority], which defaults to 0. + - [QueueTimeout][], which defaults to `null`. + +{{< figure src="/images/workspace/workspace-block-semaphore.svg" >}} + +## Run As Property + +The Run As property is an [advanced property][Advanced Properties] available on most [blocks][All Blocks]. It is used to execute the [block][] as a specified user (using a [UserCredentials][]), honouring the user's permissions and other user settings. This is required if an action needs to be performed as a particular user (e.g. reading/writing files that only that user has access to). + +Once the [block][] has finished executing, the next block to execute will run as: + +- The user specified in it's Run As property, if set. +- Otherwise, the user specified in it's closest ancestor block with the Run As property set. +- Otherwise, the user the [Execution Service][] is running as; typically this is Network Service. + +The default value of `null` also results in the [block][] executing as the user the [Execution Service][] is running as. + +If [UserCredentials][] has an invalid domain, username, password or [LogonType][UserCredentialsLogonType], a [RunAsException][] will be thrown when the [block][] is executed. + +If [UserCredentials][] has a `null` username or password, a [PropertyNullException][] will be thrown when the [block][] is executed. + +By default, the type of logon method used to authenticate the Run As user is `LogonType.Network`; this works for most scenarios. For scenarios that require a different type of logon method (e.g. connecting to a remote database), the correct [LogonType][] (e.g. `LogonType.NewCredentials`) can be specified as part of the [UserCredentials][]. + +{{< figure src="/images/set-variable/set-variable-run-as.svg" >}} + +## Block Timeout Property + +The Block Timeout property is an [advanced property][Advanced Properties] available on most [blocks][All Blocks]. It is used to set a duration of time (using a [TimePeriod][]) that the [block][] must complete its action within, otherwise a [BlockTimeoutException][] is raised. + +The default value of `null`, or a [TimePeriod][] of `0` seconds, indicates that there is no timeout. + +Negative [TimePeriod][] values will cause an [InvalidBlockTimeoutException][] to be raised when the block is executed. + +{{< figure src="/images/set-variable/set-variable-block-timeout.svg" >}} + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Workspaces][] +- [Blocks][] +- [Advanced Properties][] +- [Exceptions][] + +### Related Blocks + +- [All Blocks][] + +### Related Data Types + +- [String][] +- [TimePeriod][] + +### Related Exceptions + +- [BlockTimeoutException][] +- [InvalidBlockTimeoutException][] +- [PropertyNullException][] +- [RunAsException][] + +### External Documentation + +None + +[Description Property]: {{< ref "#description-property" >}} +[Block Timeout Property]: {{< ref "#block-timeout-property" >}} +[Semaphore Property]: {{< ref "#semaphore-property" >}} +[Run As Property]: {{< ref "#run-as-property" >}} + +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Advanced Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[SemaphoreScope]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Scope" >}} +[SemaphoreName]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Name" >}} +[SemaphoreConcurrencyLimit]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.ConcurrencyLimit" >}} +[SemaphoreQueue]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Queue" >}} +[QueuePriority]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.Priority" >}} +[QueueTimeout]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.QueueTimeout" >}} +[Tenant]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Tenant" >}} +[System]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.System" >}} +[Package]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Package" >}} +[Flow]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.Flow" >}} +[Semaphore]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MainDoc" >}} +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} +[WhatIsBlock]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} + +[UserCredentialsLogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.LogonType" >}} + +[BlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.BlockTimeoutException.MainDoc" >}} +[InvalidBlockTimeoutException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidBlockTimeoutException.MainDoc" >}} + +[PropertyNullException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}} +[RunAsException]: {{< url path="Cortex.Reference.Exceptions.Impersonation.RunAsException.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/_index.md new file mode 100644 index 000000000..c3dc56225 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/_index.md @@ -0,0 +1,6 @@ +--- +title: "Property Editors" +linkTitle: "Property Editors" +description: "Information regarding the Literal, Variable, and Expression Editors." +weight: 100 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/expression-editor.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/expression-editor.md new file mode 100644 index 000000000..a1add4898 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/expression-editor.md @@ -0,0 +1,917 @@ +--- +title: "Expression Editor" +linkTitle: "Expression Editor" +description: "Information regarding using the Expression Editor to create literal values, expressions, or use variables." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +The [Expression Editor][] is the most powerful [property editor][] and can accept [literal values][], [expressions][], and [variables][]. + +{{< figure src="/images/set-variable/set-variable-expression-empty.PNG" >}} + +## Literal Values + +A literal is an explicit value that is not calculated during the execution of the flow. A literal can be any of the following data types: + +- [String][String literal] +- [Char][Char literal] +- [Int32][Int32 literal] +- [Int64][Int64 literal] +- [Double][Double literal] +- [Single][Single literal] +- [Boolean][Boolean literal] +- [Object][Object literal] +- [Dictionary][Dictionary literal] +- [Structure][Structure literal] +- [List][List literal] + +### String literal + +{{< figure src="/images/set-variable/set-variable-expression-string.PNG" >}} + +[String][String] literals are surrounded by double quotes. For example: + +```csharp +"Example String" +``` + +The example above becomes: + +```text +Example String +``` + +Double quotes that form part of the [string][String], along with the back-slash character and any unicode character codes or hexadecimal character codes, must be escaped by a back-slash character. For example: + +```csharp +"He said \"Come here\x0021\"" +``` + +The example above becomes: + +```text +He said "Come here!" +``` + +For verbatim [string][String] literals, double quotes that form part of the [string][String] literal must be duplicated to give a single double quote character. For example: + +```csharp +@"He said ""Come here!""" +``` + +The example above becomes: + +```text +He said "Come here!" +``` + +For interpolated [strings][String], [variables][] or [expressions][] are surrounded by single curly braces. For example: + +```csharp +$"He said \"Come here {($)Name}!\"" +``` + +For further information on interpolated strings using [variables][] or [expressions][] see [String expressions][] + +In the case of interpolated verbatim [string][String] literals, double curly braces are not interpreted literally; they produce a single curly brace character. For example: + +```csharp +$@"This is a single square brace ""["", and this is a single curly brace ""{{""" +``` + +The example above becomes: + +```text +This is a single square brace "[", and this is a single curly brace "{" +``` + +For further information, see [String Literals][] + +### Char literal + +{{< figure src="/images/set-variable/set-variable-expression-char.PNG" >}} + +Char literals are single characters; they are surrounded by single quotes. For example: + +```csharp +'A' +'\u0041' +``` + +The example above becomes: + +```text +'A' +'A' +``` + +For further information, [Char Literals][] + +### Int32 literal + +{{< figure src="/images/set-variable/set-variable-expression-int.PNG" >}} + +If an integer literal value is greater than or equal to [Int32.MinValue][] or less than or equal to [Int32.MaxValue][], then it will be of type [Int32][] + +```csharp +1234 +``` + +If an integer literal value is less than [Int32.MinValue][] or greater than [Int32.MaxValue][], then it will be of type [Int64][]. + +For further information, see [Integer Literals][]. + +### Int64 literal + +{{< figure src="/images/set-variable/set-variable-expression-int64.PNG" >}} + +If an integer literal value is less than [Int32.MinValue][] or greater than [Int32.MaxValue][], then it will be of type [Int64][]. + +```csharp +2147483648 +``` + +```csharp +1234l +1234L +``` + +For further information, see [Integer Literals][]. + +### Double literal + +{{< figure src="/images/set-variable/set-variable-expression-double.PNG" >}} + +By default, floating point literals are of type [Double][Double]. + +```csharp +1234.456 +``` + +The suffix `d` or `D` can used to create a floating point literal of type [Double][Double], but is unnecessary. + +```csharp +1234.456d +1234.456D +``` + +For further information, see [Real Literals][]. + +### Single literal + +{{< figure src="/images/set-variable/set-variable-expression-single.PNG" >}} + +If it is necessary to create an floating point literal of type [Single][] with a value greater than or equal to [Single.MinValue][] or less than or equal to [Single.MaxValue][], then the floating point literal must be suffixed by the character `f` or `F`. For example: + +```csharp +1234.456f +1234.456F +``` + +For further information, see [Real Literals][]. + +### Boolean literal + +{{< figure src="/images/set-variable/set-variable-expression-boolean.PNG" >}} + +A [Boolean][] literal represents a truth-value of either `true` or `false`. + +```json +true or false +``` + +For further information, see [Boolean Literals][]. + +### Object literal + +Currently, creating an object using literal syntax is not supported. + +### Dictionary literal + +Currently, creating a dictionary using literal syntax is not supported; any attempt to make a dictionary using literal syntax will create a [Structure][] instead. + +### Structure literal + +{{< figure src="/images/set-variable/set-variable-expression-structure.PNG" >}} + +[Structures][Structure] are a special type of [Dictionary][] that always have [string][String] keys. + +```json +{ + "Name1" : "", + "Name2" : 1, + "Name3" : true, + "Name4" : {}, + "Name5" : [], + "Name6" : null +} +``` + +They differ from a [Dictionary][] in the syntax used for accessing the item: + +- [Dictionary][] items can be accessed using [Index expressions][] +- [Structure][] items can be accessed using [Property expressions][] or [Index expressions][] + +### List literal + +{{< figure src="/images/set-variable/set-variable-expression-list.PNG" >}} + +A [List][] is an object that consists of a number of ordered items that can be of any [data type][Data Type]. + +```json +[ + "Example String", + 1, + true, + {}, + [], + null +] +``` + +[Lists][List] may be heterogeneous, where the items may be of different [data types][Data Type], or homogeneous, when the items are all of the same [data type][Data Type]. + +## Variables + +{{< figure src="/images/set-variable/set-variable-expression-variable.PNG" >}} + +[Variables][Variables Concept] are named containers for storing values of any [data type][Data Type]; a [variable's][Variables Concept] value can be read, updated, replaced, or removed using variable syntax; where the variable name is prefixed with `($)` (e.g. `($)VariableName`). + +Variables can be used within [expressions][]. + +## Expressions + +An expression is a combination of [operands][] (i.e. [variables][], [literals][literal values], calls to [methods][] and [properties][PropertiesC#] exposed on [data types][Data Type]) and [operators][] (i.e. =, +, -, *, /) that will be evaluated when the flow execution reaches the block. + +Expressions use the syntax of the [C#][] [programming language][]. + +Types of expressions: + +- [Arithmetic][Arithmetic expressions] +- [Boolean][Boolean expressions] +- [Comparison][Comparison expressions] +- [String][String expressions] +- [Dictionary][Dictionary expressions] +- [Structure][Structure expressions] +- [List][List expressions] +- [Constructors][Constructor expressions] +- [Methods][Method expressions] +- [Properties][Property expressions] +- [Enums][Enum expressions] +- [Casting][Casting expressions] +- [Indexes][Index expressions] +- [Decomposition][Decomposition expressions] ([output property][Output Properties] only) + +### Arithmetic expressions + +{{< figure src="/images/set-variable/set-variable-expression-arithmetic.PNG" >}} + +The following [operators][] perform arithmetic operations with [operands][] that have numeric values. + +In the examples below assume: + +- `($)Int1` has been set to `6` +- `($)Int2` has been set to `3` + +| Expression | Result | Notes | +|---------------------------|--------|-----------| +| `($)Int1 + ($)Int2` | `9` | Add | +| `($)Int1 - ($)Int2` | `3` | Subtract | +| `($)Int1 * ($)Int2` | `18` | Multiply | +| `($)Int1 / ($)Int2` | `2` | Divide | +| `($)Int1 % ($)Int2` | `0` | Remainder | + +For further information, see [Arithmetic Operators][]. + +### Boolean expressions + +{{< figure src="/images/set-variable/set-variable-expression-boolean-and.PNG" >}} + +The following [operators][] perform logical operations with [operands][] that have boolean values. + +In the examples below assume: + +- `($)Bool1` has been set to `false` +- `($)Bool2` has been set to `true` + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `($)Bool1 && ($)Bool2` | `false` | AND | +| `($)Bool2 \|\| ($)Bool1` | `true` | OR | +| `($)Bool1 ^ ($)Bool2` | `true` | XOR | +| `!($)Bool1` | `true` | NOT | + +For further information, see [Boolean Logical Operators][]. + +### Comparison expressions + +{{< figure src="/images/set-variable/set-variable-expression-comparison.PNG" >}} + +The following [operators][] perform comparison operations with [operands][]. + +In the examples below assume: + +- `($)Int1` has been set to `1` +- `($)Int2` has been set to `2` + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `($)Int1 == ($)Int2` | `false` | Equal | +| `($)Int1 != ($)Int2` | `true` | Not Equal | +| `($)Int1 > ($)Int2` | `false` | Greater Than | +| `($)Int1 >= ($)Int2` | `false` | Greater Than or Equal | +| `($)Int1 < ($)Int2` | `true` | Less Than | +| `($)Int1 <= ($)Int2` | `true` | Less Than or Equal | + +For further information, see [Equality Operators][], [Comparison Operators][], and [Object Equality][]. + +### String expressions + +There are three types of string expressions: + +- [Concatenated Strings][] +- [Interpolated Strings][] +- [Verbatim Strings][] + +If a data type is used in a string expression that is not a [String][], then it will be [implicitly cast][] to a [String][] as part of the expression. + +In all of the examples below assume: + +- `($)String1` has been set to `"hello"` +- `($)String2` has been set to `"world"` +- `($)Int` has been set to `1234` + +#### Concatenated Strings + +{{< figure src="/images/set-variable/set-variable-expression-concatenated-string.PNG" >}} + +Concatenation is the process of appending one [String][] to the end of another [String][]. You concatenate strings by using the `+` [operator][operators]. + +| Expression | Result | Notes | +|---------------------------------------|------------------------------|------------------------------------| +| `($)String1 + " " + ($)String2` | `"hello world"` | | +| `($)String1 + " " + ($)Int` | `"hello 1234"` | The variable `($)Int` is [implicitly cast][] to a [String][String] as part of the expression | + +For further information, see [String concatenation][]. + +#### Interpolated Strings + +{{< figure src="/images/set-variable/set-variable-expression-interpolated-string.PNG" >}} + +Interpolation is the process of inserting expressions and variables into a [String][]. An interpolated string is declared by prefixing the string with the `$` character. + +| Expression | Result | Notes | +|---------------------------------------|------------------------------|------------------------------------| +| `$"{($)String1} {($)String2}"` | `"hello world"` | | +| `$"{($)String1} {($)Int}"` | `"hello 1234"` | The variable `($)Int` is [implicitly cast][] to a [String][String] as part of the expression | +| `$"{($)String1} {($)Int + 1}"` | `"hello 1235"` | The expression `($)Int + 1` is evaluated and the result is [implicitly cast][] to a [String][String] as part of the expression | + +For further information, see [String interpolation][]. + +#### Verbatim Strings + +{{< figure src="/images/set-variable/set-variable-expression-verbatim-string.PNG" >}} + +A verbatim string identifies that characters within the string should be processed literally, and do not need to be escaped. However, the following exceptions apply: + +- In both Verbatim and Interpolated Verbatim strings the double quote character `"` is escaped by prefixing it with another double quote character +- In Interpolated Verbatim strings the curly brace characters `{` and `}` are escaped by prefixing them with the same curly brace character + +| Expression | Result | Notes | +|---------------------------------------|------------------------------|------------------------------------| +| `@"c:\programs\file.txt"` | `"c:\\programs\\file.txt"` | | +| `@"They said ""Hello!"""` | `"They said \"Hello!\""` | The `"` character is escaped| +| `$@"{{ Some Text }}"` | `"{ Some Text }"` | Interpolated Verbatim String, The curly brace characters are escaped | +| `$@"c:\programs\{($)String1}.txt"` | `"c:\\programs\\hello.txt"` | Interpolated Verbatim String | + +For further information, see [Verbatim string literals][] and [Verbatim String Interpolation][]. + +### Dictionary expressions + +[Dictionaries][Dictionary] can be created using [Constructor expressions][] and their items can be accessed using [Index expressions][]. + +For examples of creating Dictionaries using constructor expressions, see [Create a Dictionary<TKey, TItem>][Create a Dictionary]. + +### Structure expressions + +[Structures][Structure] can be created using [Constructor expressions][] and their items can be accessed using [Property expressions][] (keys must follow [C# identifier naming rules][]) or [Index expressions][] (keys do not need to follow [C# identifier naming rules][]). + +For examples of creating Structures using constructor expressions, see [Create a Structure][]. + +### List expressions + +[Lists][List] can be created using [Constructor expressions][] and their items can be accessed using [Index expressions][]. + +For examples of creating Lists using constructor expressions, see [Create a List<TItem>][Create a List]. + +### Constructor expressions + +{{< figure src="/images/set-variable/set-variable-expression-constructor.PNG" >}} + +Constructors can be used to create a new instance of a [Data Type][]. A [Data Type][] can have multiple constructors, each with different parameters that are used to create the new instance. + +Methods on how to create a new instance of a [Data Type][] can be found in the relevant documentation for that [Data Type][Reference Data Types]; information regarding how to create a new [Data Type][] using a constructor can be found in the "Remarks" section under "Create a/an <DataType>" (where <DataType> is replaced by the type's name). + +The following examples show two ways a [DateTimeOffset][] can be created using a constructor: + +In the examples below assume the variable `($)Year` has been set to `2022`. + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `new DateTimeOffset()` | `0001-01-01T00:00:00+00:00` | `12AM 1st January 0001` with `0` hour UTC offset, the default for a new DateTimeOffset with no parameters | +| `new DateTimeOffset(($)Year, 7, 1, 14, 0, 0, 0, new TimeSpan(1, 0, 0))` | `2022-07-01T14:00:00+01:00` | `2PM 1st July 2022` with `1` hour UTC offset | + +Note that some [Data Types][Data Type] should be created via [literal values][] instead of their constructors, these include: + +- [String][String literal] +- [Char][Char literal] +- [Int32][Int32 literal] +- [Int64][Int64 literal] +- [Double][Double literal] +- [Single][Single literal] +- [Boolean][Boolean literal] + +For further information, see [Constructors][]. + +### Method expressions + +{{< figure src="/images/set-variable/set-variable-expression-method.PNG" >}} + +Methods can be used to execute specific functionality. The methods accessible are defined by the [Data Type][], and information regarding methods can be found in the relevant documentation for that [Data Type][Reference Data Types]. + +Methods can have parameters passed into them that are then used to execute the functionality, not all methods have parameters. The same method can be defined multiple times, each with different sets of parameters. + +In the examples below assume the variable `($)Int` has been set to `1`. + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `TimePeriod.FromSeconds(60)` | `{"Years": 0, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 1, "Seconds": 0, "Milliseconds": 0}` | Method with parameters | +| `($)Int.ToString()` | `"1"` | Method without parameters | +| `($)Int.ToString("P0")` | `"100%"` | The `ToString()` method can take parameters in order to format the result. In this case `1` was converted into a percent with zero decimal places | + +For further information, see [Methods][Methods External]. + +### Property expressions + +{{< figure src="/images/set-variable/set-variable-expression-properties.PNG" >}} + +Properties can be used to read data from and/or write data to a [Data Type][]. The properties accessible are defined by the [Data Type][], and information regarding properties can be found in the relevant documentation for that [Data Type][Reference Data Types]. + +Properties can be read-write, read-only, or write-only (extremely rare) depending on the access specified by the [Data Type][]. + +Whilst [Structures][Structure] are [Collections][Collection], they also allow for their keys to be accessed as properties. + +In the examples below assume: + +- `($)TimePeriod` has been set to `{"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}` +- `($)Structure` has been set to `{"FirstKey": 1, "SecondKey": 2}` + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `DateTimeOffset.UtcNow` | `2022-07-01T13:00:00.0000000+00:00` | Read-only property, this only works in [Input Properties][] | +| `($)TimePeriod.Years` | `1` | Read-write property, this can be used in [Input][Input Properties], [Output][Output Properties], and [InputOutput Properties][]. The result column shows reading the property; writing to the property can be achieved by using any [Output Property][Output Properties]. | +| `($)Structure.FirstKey` | `1` | Read-write property, this can be used in [Input][Input Properties], [Output][Output Properties], and [InputOutput Properties][]. The result column shows reading the property; writing to the property can be achieved by using any [Output Property][Output Properties].| + +For further information, see [Properties][]. + +### Enum expressions + +{{< figure src="/images/set-variable/set-variable-expression-enum.PNG" >}} + +[Enum][] data types have a defined set of values, where each value has an associated [String][] name and [Int32][] value. Information regarding values can be found in the relevant documentation for that [Data Type][Reference Data Types]. + +Values within an [Enum][] can be accessed in the same way as properties or can they can be [cast][Casting expressions] from an [Int32][] value. + +In the examples below assume the variable `($)Int` has been set to `6`. + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `DayOfWeek.Sunday` | `DayOfWeek.Sunday` | Where the name is `"Sunday"` and the value is `0` | +| `(DayOfWeek)($)Int` | `DayOfWeek.Saturday` | [Int32][] cast to an [Enum][]. Where the name is `"Saturday"` and the value is `6` | + +For further information, see [Enumeration types][]. + +### Casting expressions + +{{< figure src="/images/set-variable/set-variable-expression-casting.PNG" >}} + +[Data Types][Data Type] can be cast to other [Data Types][Data Type] through the use of explicit casting, this can sometimes result in the loss of information when converting to a type that does not store the same amount of information. Information regarding which types a [Data Type][] can cast to can be found in the "Summary" section under "Can be cast to" in the relevant documentation for that [Data Type][Reference Data Types]. + +[Data Types][Data Type] can be used as other [Data Types][Data Type] through the use of implicit casting, this is an automatic process that requires no expression syntax. Information regarding which types a [Data Type][] can be used as can be found in the "Summary" section under "Can be used as" in the relevant documentation for that [Data Type][Reference Data Types]. + +In the examples below assume the variable `($)Int` has been set to `6`. + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `(DayOfWeek)($)Int` | `DayOfWeek.Saturday` | [Int32][] cast to an [Enum][]. Where the name is `"Saturday"` and the value is `6` | +| `(Int16)($)Int` | `6` | An [Int32][] can be cast to an [Int16][] as long as value is from `-32,768` through `32,767` | +| `(Int32)1.9` | `1` | Casting a [Double][] to an [Int32][] will cause any decimal places to be lost | +| `($)Int` | `6.0` | When using a block property of type [Double][] an [Int32][] is implicitly cast to [Double][] without any expression syntax | + +For further information, see [Explicit Conversions][] and [Implicit Conversions][]. + +### Index expressions + +{{< figure src="/images/set-variable/set-variable-expression-index.PNG" >}} + +[Data Types][Data Type] that are [Collections][] or [String][] can have their items accessed using index notation: + +- `[0]` gets the first item +- `[1]` gets the second item +- `["key"]` gets the item with the key `"key"`. + +Ranges can also be used within index notation: + +- `[0..3]` gets three items from the first item (inclusively) (i.e. the first, second, and third item) +- `[^1]` gets the last item +- `[^2]` gets the second to last item +- `[..]` gets all items +- `[..3]` gets three items from the first item (inclusively) (i.e. the first, second, and third item) +- `[3..]` gets all items from the fourth item (inclusively) (i.e. the fourth to the last item) + +For further information on index and range syntax, see [Indices and Ranges][]. + +In the examples below assume: + +- `($)List` has been set to `[1, 2, 3, 4, 5]` +- `($)Dictionary` of type `Dictionary` has been set to `{"FirstKey": 1, "SecondKey": 2}` +- `($)Structure` has been set to `{"FirstKey": 1, "SecondKey": [1, 2, 3]}` +- `($)String` has been set to `"Some Text"`. + +| Expression | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `($)List[2]` | `3` | The third item in the list is returned | +| `($)List[0..2]` | `[1, 2]` | The first and second item in the list are returned | +| `($)List[^2]` | `4` | The second to last item in the list is returned | +| `($)List[^2..^0]` | `[4, 5]` | The second to last and the last item in the list are returned | +| `($)List[1..^1]` | `[2, 3, 4]` | The second item to the second to last item in the list are returned | +| `($)List[..]` | `[1, 2, 3, 4, 5]` | All items in the list are returned | +| `($)List[..2]` | `[1, 2]` | The first item and the second item in the list are returned | +| `($)List[2..]` | `[3, 4, 5]` | The third item to the last item in the list are returned | +| `($)Dictionary["FirstKey"]` | `1` | The item with the key `"FirstKey"` is returned | +| `($)Structure["SecondKey"]` | `[1, 2, 3]` | The item with the key `"SecondKey"` is returned | +| `($)Structure["SecondKey"][0]` | `1` | The first item within the item with key `"SecondKey"` is returned | +| `($)String[0]` | `'S'` | The first character in the string is returned | + +### Decomposition expressions + +{{< figure src="/images/set-variable/set-variable-expression-decomposition.PNG" >}} + +Decomposition expressions are used to save selected values from an [Output property][Output properties] to multiple [variables][Variables Concept]. + +{{% alert title="Note" %}} +This is currently only supported by output properties. +{{% /alert %}} + +Decomposition syntax follows a similar pattern to a `JSON` object: + +- each `key` is the property path expression, where `$` is the root of the output value. +- each `value` is the variable name, prefixed with `($)`. + +```json +{ + "$.property.firstPath": ($)FirstVariable, + "$.property.secondPath": ($)SecondVariable +} +``` + +The examples below assumes that the output value contains the following data: + +``` json +{ + "company": { + "name": "Company Name", + "departments": [ + { + "name": "HR", + "employees": [ + { + "name": "Joe Blogs", + "id": "101" + }, + { + "name": "Jane Doe", + "id": "102" + } + ] + }, + { + "name": "Admin", + "employees": [ + { + "name": "Jane Blogs", + "id": "103" + }, + { + "name": "Joe Doe", + "id": "104" + } + ] + } + ] + } +} +``` + +#### Decomposing an object property + +To save the `departments` property, the syntax would be: + +```json +{ + "$.company.departments": ($)ListOfDepartments +} +``` + +In this example, the variable `($)ListOfDepartments` will be set to the following value: + +```json +[ + { + "name": "HR", + "employees": [ + { + "name": "Joe Blogs", + "id": "101" + }, + { + "name": "Jane Doe", + "id": "102" + } + ] + }, + { + "name": "Admin", + "employees": [ + { + "name": "Jane Blogs", + "id": "103" + }, + { + "name": "Joe Doe", + "id": "104" + } + ] + } +] +``` + +#### Decomposing an item in a list + +To save the first department, the syntax would be: + +```json +{ + "$.company.departments[0]": ($)FirstDepartment +} +``` + +In this example, the variable `($)FirstDepartment` will be set to the following value: + +```json +{ + "name": "HR", + "employees": [ + { + "name": "Joe Blogs", + "id": "101" + }, + { + "name": "Jane Doe", + "id": "102" + } + ] +} +``` + +#### Decomposing the last item in a list + +To save the last `employee` of the first department, the syntax would be: + +```json +{ + "$.company.departments[0].employees[-1]": ($)LastEmployeeOfFirstDepartment +} +``` + +In this example, the variable `($)LastEmployeeOfFirstDepartment` will be set to the following value: + +```json +{ + "name": "Jane Doe", + "id": "102" +} +``` + +#### Decomposing multiple properties at the same time + +To save the `id` and `name` of the first `employee` of the first department, the syntax would be: + +```json +{ + "$.company.departments[0].employees[0].id": ($)FirstEmployeeId, + "$.company.departments[0].employees[0].name": ($)FirstEmployeeName +} +``` + +In this example, the variable `($)FirstEmployeeId` will be set to the following value: + +```json +"101" +``` + +And the variable `($)FirstEmployeeName` will be set to the following value: + +```json +"Joe Blogs" +``` + +## Remarks + +### Known Limitations + +#### Cannot Create Objects using Literal Syntax + +Currently, creating an object using literal syntax is not supported. + +Objects can be created using expressions, for more information see [Constructor expressions][]. + +#### Cannot Create Dictionaries using Literal Syntax + +Currently, creating a dictionary using literal syntax is not supported; any attempt to make a dictionary using literal syntax will create a [Structure][] instead. + +Dictionaries can be created using expressions, for more information see [Dictionary expressions][]. + +#### When using variables of the same name the closest scoped is used + +It is possible to create multiple [variables][Variables: What Is a Variable] with the same name in the [Variables Grid][]. When using the same name in different [workspaces][workspace], the variable with the closest scope will be used. + +For example: + +- `Top-Level` workspace has the variable `($)Variable` +- `Child-Level` workspace also has the variable `($)Variable` + +When executing a block in `Child-Level` that uses `($)Variable`, the variable that is used is the variable defined in `Child-Level`. + +This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario. + +## See Also + +### Related Concepts + +- [Workspaces][] +- [Literal Editor][] +- [Variable Editor][] +- [Variables][Variables Concept] +- [Data Types][Data Type] +- [Object Casting][] + +### Related Blocks + +- [All Blocks][Blocks] + +### Related Data Types + +- [All Data Types][Reference Data Types] + +### External Documentation + +- [Boolean Literals][] +- [Char Literals][] +- [Integer Literals][] +- [Real Literals][] +- [String Literals][] +- [Arithmetic Operators][] +- [Boolean Logical Operators][] +- [Comparison Operators][] +- [Equality Operators][] +- [String concatenation][] +- [String interpolation][] +- [Verbatim string literals][] +- [Verbatim String Interpolation][] +- [Constructors][] +- [Methods][Methods External] +- [Properties][] +- [C# identifier naming rules][] +- [Enumeration types][] +- [Explicit Conversions][] +- [Implicit Conversions][] +- [Indices and Ranges][] + +[literal values]: {{< ref "#literal-values" >}} +[expressions]: {{< ref "#expressions" >}} +[variables]: {{< ref "#variables" >}} + +[String literal]: {{< ref "#string-literal" >}} +[Char literal]: {{< ref "#char-literal" >}} +[Int32 literal]: {{< ref "#int32-literal" >}} +[Int64 literal]: {{< ref "#int64-literal" >}} +[Single literal]: {{< ref "#single-literal" >}} +[Double literal]: {{< ref "#double-literal" >}} +[Boolean literal]: {{< ref "#boolean-literal" >}} +[Object literal]: {{< ref "#object-literal" >}} +[Dictionary literal]: {{< ref "#dictionary-literal" >}} +[Structure literal]: {{< ref "#structure-literal" >}} +[List literal]: {{< ref "#list-literal" >}} +[Concatenated Strings]: {{< ref "#concatenated-strings" >}} +[Interpolated Strings]: {{< ref "#interpolated-strings" >}} +[Verbatim Strings]: {{< ref "#verbatim-strings" >}} + +[Arithmetic expressions]: {{< ref "#arithmetic-expressions" >}} +[Boolean expressions]: {{< ref "#boolean-expressions" >}} +[Comparison expressions]: {{< ref "#comparison-expressions" >}} +[String expressions]: {{< ref "#string-expressions" >}} +[Dictionary expressions]: {{< ref "#dictionary-expressions" >}} +[Structure expressions]: {{< ref "#structure-expressions" >}} +[List expressions]: {{< ref "#list-expressions" >}} +[Constructor expressions]: {{< ref "#constructor-expressions" >}} +[Method expressions]: {{< ref "#method-expressions" >}} +[Property expressions]: {{< ref "#property-expressions" >}} +[Enum expressions]: {{< ref "#enum-expressions" >}} +[Casting expressions]: {{< ref "#casting-expressions" >}} +[Index expressions]: {{< ref "#index-expressions" >}} +[Decomposition expressions]: {{< ref "#decomposition-expressions" >}} + +[Data Type]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} + +[property editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.MainDoc" >}} +[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 Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Reference Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[Collections]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[Create a Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int32.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Int32.MaxValue" >}} +[Int32.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Int32.MinValue" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Create a List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} +[Single.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Single.MaxValue" >}} +[Single.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Single.MinValue" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Collection]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Create a Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[Variables Concept]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Variables: What Is a Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[Object Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectEquality.MainDoc" >}} + +[Enum]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} + +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} +[implicitly cast]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ImplicitCast" >}} + +[Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Expression Editor]: {{< url path="Cortex.Guides.Studio.ExpressionEditor.MainDoc" >}} + +[Variables Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.VariablesGrid" >}} + +[Boolean Literals]: {{< url path="MSDocs.CSharp.BooleanLiterals" >}} +[Char Literals]: {{< url path="MSDocs.CSharp.CharLiterals" >}} +[Integer Literals]: {{< url path="MSDocs.CSharp.IntegerLiterals" >}} +[Real Literals]: {{< url path="MSDocs.CSharp.RealLiterals" >}} +[String Literals]: {{< url path="MSDocs.CSharp.StringLiterals" >}} +[Arithmetic Operators]: {{< url path="MSDocs.CSharp.ArithmeticOperators" >}} +[Boolean Logical Operators]: {{< url path="MSDocs.CSharp.BooleanLogicalOperators" >}} +[Comparison Operators]: {{< url path="MSDocs.CSharp.ComparisonOperators" >}} +[Equality Operators]: {{< url path="MSDocs.CSharp.EqualityOperators" >}} +[Constructors]: {{< url path="MSDocs.CSharp.Constructors" >}} +[Methods External]: {{< url path="MSDocs.CSharp.Methods" >}} +[Properties]: {{< url path="MSDocs.CSharp.Properties" >}} +[Enumeration types]: {{< url path="MSDocs.CSharp.EnumerationTypes" >}} +[Explicit Conversions]: {{< url path="MSDocs.CSharp.ExplicitConversions" >}} +[Implicit Conversions]: {{< url path="MSDocs.CSharp.ImplicitConversions" >}} +[Indices and Ranges]: {{< url path="MSDocs.CSharp.IndicesAndRanges" >}} +[String concatenation]: {{< url path="MSDocs.DotNet.Api.System.String.ConcatGuide" >}} +[C# identifier naming rules]: {{< url path="MSDocs.CSharp.IdentifierNamingRules" >}} +[String interpolation]: {{< url path="MSDocs.CSharp.Interpolation" >}} +[Verbatim string literals]: {{< url path="MSDocs.CSharp.Verbatim" >}} +[Verbatim String Interpolation]: {{< url path="MSDocs.CSharp.InterpolatedVerbatim" >}} + +[C#]: {{< url path="Cortex.Reference.Glossary.A-E.CSharp" >}} +[operands]: {{< url path="Cortex.Reference.Glossary.K-O.Operand" >}} +[operators]: {{< url path="Cortex.Reference.Glossary.K-O.Operator" >}} +[PropertiesC#]: {{< url path="Cortex.Reference.Glossary.P-T.PropertyCSharp" >}} +[methods]: {{< url path="Cortex.Reference.Glossary.K-O.Method" >}} +[programming language]: {{< url path="Cortex.Reference.Glossary.P-T.ProgrammingLanguage" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/literal-editor.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/literal-editor.md new file mode 100644 index 000000000..b98c07f71 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/literal-editor.md @@ -0,0 +1,74 @@ +--- +title: "Literal Editor" +linkTitle: "Literal Editor" +description: "Information regarding using the Literal Editor." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Available Types + +TODO: + +- The literal editor will have one or more available types, these types will be either Complex or Basic Types +- The types available to the literal editor are restricted by the block property. +- It is possible to switch the type of the literal editor to any available type. + +### Basic Types + +TODO: + +- Single Editor + +TODO: Image of basic literal editor + +### Complex Types + +TODO: + +- Nested editors within a complex type +- List and Dictionary Editors + +TODO: Image of complex literal editor + +### Switching Type + +TODO: + +- What are DataType and CurrentType? +- An editor can be switched using the type selector (accessed by clicking on the property name) + +TODO: Image of type selector + +## Remarks + +### Known Limitations + +TODO: + +- There is no literal support for Collection Types or types that have constructors with no parameters. + +## See Also + +### Related Concepts + +TODO + +### Related Blocks + +TODO + +### Related Data Types + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/variable-editor.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/variable-editor.md new file mode 100644 index 000000000..e1d8e2409 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/property-editors/variable-editor.md @@ -0,0 +1,102 @@ +--- +title: "Variable Editor" +linkTitle: "Variable Editor" +description: "Information regarding using the Variable Editor." +weight: 100 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Using Variables + +TODO: + +- You can use any available variable. +- Available variables are restricted by the scope of the currently selected block +- All available variables will be shown when the variable editor is empty; typing in the editor will filter the available variables with those that match (contains text) on either the variable name or scope + +TODO: Image of using a variable + +TODO: Image of selecting available variables + +### Scoped Variables + +TODO: + +- Available variables are scoped by the workspace of the block selected +- Can see variables of the same name that are on accessible scopes +- Link to known limitation. If there are two or more variables with the same name, the variable with the closest scope will be always used even if another is selected + +TODO: Image of scoped variables (different names and same names) + +### Accessing Variable Properties or Indexes + +TODO: + +- Properties and indexes can be accessed from the Variable editor +- Translation error shown in messages viewer when using properties or indexes incorrectly for variable that is not dynamic + +TODO: Image of accessing variable property and index + +## Missing Variables + +TODO: + +- If a variable does not exist, then a orange border will be shown around the Variable editor +- It is possible to create a new variable from a missing one using the variable editor + +TODO: Image of orange border for missing variables + +## Creating Variables + +TODO: + +- If a variable does not already exist, the variable editor can be used to create a new one at the current scope +- If the variable name is invalid ([C# identifier naming rules][]) then there will be no option to create a new variable + +TODO: Image of option to create a new variable + +## Renaming Variables + +TODO: + +- If a variable editor already contains a reference to a variable that exists, typing the name of a non-existent variable will provide the option to rename the previously selected variable (and all references to it within the flow) to the new variable name +- If the variable name is invalid ([C# identifier naming rules][]) then there will be no option to rename the variable +- Renaming a variable does not include any index or method expressions (e.g. renaming to `($)NewVar.ToString()` will rename the selected variable to `($)NewVar`) + +TODO: Image of option to rename a variable + +## Remarks + +### Known Limitations + +TODO: + +- If there are two or more variables with the same name, the variable with the closest scope will be always used even if another is selected +- Currently, available variables are not restricted based on the type of the variable and if that is valid for the selected property + +## See Also + +### Related Concepts + +TODO + +### Related Blocks + +TODO + +### Related Data Types + +TODO + +### External Documentation + +TODO + +[C# identifier naming rules]: {{< url path="MSDocs.CSharp.IdentifierNamingRules" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/what-is-a-block-property.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/what-is-a-block-property.md new file mode 100644 index 000000000..0fec4c150 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/block-properties/what-is-a-block-property.md @@ -0,0 +1,152 @@ +--- +title: "What is a Block Property?" +linkTitle: "What is a Block Property?" +description: "Information regarding the anatomy of block properties, types of property and their appearance, and configuring properties using the available property editors." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +[Blocks][block] are configured using Block Properties. Properties pass data to the block which is then used to perform an action, or branch based on a condition within a [flow][]. + +## Anatomy of a Block Property + +There are three types of block property, each type can be configured using one of its supported editors: + +- [Input Properties][] +- [Output Properties][] +- [InputOutput Properties][] + +### Input Properties + +Input properties are used to provide values to a [block][]. These properties are used in the block's execution (e.g. a block to send emails would have input properties for specifying things like the sender, recipients, summary, body, attachments etc.). + +#### Supported Editors + +Input properties can be configured using the following editors: + +- [Literal Editor][] +- [Variable Editor][] +- [Expression Editor][] + +{{< figure src="/images/editable/editor-types.png" >}} + +### Output Properties + +Output properties are used to save values from a [block][]. These properties can be saved to a variable or [decomposed][Decomposing Output Properties] to be saved into multiple variables during the block's execution. + +Values from Output properties can be [discarded][Discarding Outputs], this means they will not be saved to any variable. + +#### Supported Editors + +Output properties can be configured using the following editors: + +- [Variable Editor][] + +{{< figure src="/images/editable/variable-editor.png" >}} + +- [Expression Editor][] using [decomposition][Decomposing Output Properties] + +{{< figure src="/images/editable/expression-editor.png" >}} + +#### Decomposing Output Properties + +Output values can be [decomposed][Decomposition expressions] to allow the saving of different parts of the value to different variables. + +To [decompose][Decomposition expressions] an output value, the output property will need to be set to an expression. + +#### Discarding Outputs + +Output values can be discarded, instead of saving them to a variable. + +Common reasons for discarding include: + +- Discarding the exception output from [Handle Exception blocks][] +- Discarding unwanted output values from blocks such as the [Execute SSH Command][] block that have multiple Output properties + +To discard an output value, the Output property should use the built-in `($)_` variable. + +{{< figure src="/images/discarded-variable.PNG" >}} + +### InputOutput Properties + +InputOutput properties are used to provide values to a [block][]. These properties are used, updated and saved back to a variable during the block's execution. + +#### Supported Editors + +InputOutput properties can be configured using the following editors: + +- [Variable Editor][] + +{{< figure src="/images/editable/variable-editor.png" >}} + +The icons used for InputOutput properties are light blue to distinguish them from [Input Properties][]. + +## Remarks + +### Known Limitations + +#### The Literal Editor is not Supported for all Input Properties + +Currently, not all [Data Types][] support the use of the [Literal Editor][], such as: + +- [Collections][] +- [Data Types][] without a constructor that contains parameters + +Information regarding which editors are supported for a [Data Type][Data Types] can be found in the "Remarks" section under "Property Editor Support" in the relevant documentation for that [Data Type][Data Types]. + +In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Property Editors][] +- [Variables][] +- [Data Types][Fundamentals Data Types] +- [Executions][] +- [Exceptions][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Input Properties]: {{< ref "#input-properties" >}} +[Output Properties]: {{< ref "#output-properties" >}} +[InputOutput Properties]: {{< ref "#inputoutput-properties" >}} +[Decomposing Output Properties]: {{< ref "#decomposing-output-properties" >}} +[Discarding Outputs]: {{< ref "#discarding-outputs" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Handle Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.MainDoc" >}} +[Execute SSH Command]: {{< url path="Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Property Editors]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.MainDoc" >}} +[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" >}} +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Decomposition expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.DecompositionExpressions" >}} + +[Fundamentals Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} + +[Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} +[Collections]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} + +[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" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/handling-exceptions-within-a-block.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/handling-exceptions-within-a-block.md new file mode 100644 index 000000000..22299a50a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/handling-exceptions-within-a-block.md @@ -0,0 +1,54 @@ +--- +title: "Handling Exceptions within a Block" +linkTitle: "Handling Exceptions within a Block" +description: "Information regarding handling exceptions within a block." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +Exceptions within a block can be handled at the following levels: + +- The [block level][] (Highest Priority) +- The [workspace level][] +- The [flow level][] (Lowest Priority) + +Exceptions thrown within the execution of a [block][] can be handled at the [block level][] by connecting any [Handle Block Exception block][] to the exception output port. Multiple [Handle Block Exception blocks][Handle Block Exception block] can be [chained][] to handle different exceptions. + +For more information, see [Handling Exceptions][]. + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][block] +- [Exceptions][] + +### Related Blocks + +- [Handle Block Exception][Handle Block Exception block] + +### External Documentation + +None + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[flow level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.FlowLevel" >}} +[workspace level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.WorkspaceLevel" >}} +[chained]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.ChainingExceptions" >}} +[block level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.BlockLevel" >}} +[Handle Block Exception block]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/what-is-a-block.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/what-is-a-block.md new file mode 100644 index 000000000..17accad8b --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/blocks/what-is-a-block.md @@ -0,0 +1,243 @@ +--- +title: "What is a Block?" +linkTitle: "What is a Block?" +description: "Information regarding the anatomy of a block, types of blocks and their appearance, connecting blocks, and block properties." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +A block is used to perform an action, or branch based on a condition within a [flow][]. + +Blocks are organised into palettes based on the type of object they operate on or the system they interact with (e.g. Blocks that operate on Lists can be found in the Lists palette). Blocks can be dragged from a palette on to a [workspace][], and connected to one another to create the logic of the [flow][]. + +## Anatomy of a Block + +There are five types of block, each type has its own image, connection ports and properties: + +- [Flow Control Blocks][] +- [Action Blocks][] +- [Decision Blocks][] +- [Exception Handling Blocks][] +- [Workspace Blocks][] + +### Flow Control Blocks + +Flow Control blocks are used to start or end a [flow][] or [workspace][]. + +#### Block Image + +{{< figure src="/images/flow-control-blocks.svg" >}} + +- Flow Control blocks are square shaped +- Flow Control blocks are smaller than [Action Blocks][] +- Flow Control blocks have a pale blue background + +#### Connection Ports + +Flow Control Blocks that start a [flow][] or [workspace][] have the following connection ports: + +- One output port located on the bottom of the block + +An [execution][] moves to the input port of the block connected to the output port. + +Flow Control Blocks that end a [flow][] or [workspace][] have the following connection ports: + +- One input port located on the top of the block + +An [execution][] passes through the input port, and ends the [flow][] or [workspace][] depending on the logic of the block. + +### Action Blocks + +Action blocks are used to perform an action within a [flow][]. They can operate on an object or interact with a system. + +Exceptions thrown by Action blocks can be handled by connecting a [Handle Block Exception block][Handle Block Exception blocks] to the red output port. + +#### Block Image + +{{< figure src="/images/action-blocks.svg" >}} + +- The icon of the Action block shows what object or system it interacts with +- The icon in the bottom right of the Action block provides further information into what type of action or interaction it will take +- Action blocks are square shaped +- Action blocks have a pale blue background + +#### Connection Ports + +Action blocks have the following connection ports: + +- One input port located on the top of the block +- One output port located on the bottom of the block +- One red exception output port located on the right of the block + +An [execution][] passes through the input port, executes the block, and if no [exception][] occurs, moves to the input port of the block connected to the output port; if an exception occurs the execution moves to the exception input port of the [exception handling block][Exception Handling Blocks] connected to the exception output port. + +### Decision Blocks + +Decision blocks are used to branch within a [flow][] based on a condition. + +#### Block Image + +{{< figure src="/images/decision-blocks.svg" >}} + +- The icon of the Decision block shows what object or system it interacts with +- Decision blocks are diamond shaped +- Decision blocks have a pale blue background + +#### Connection Ports + +Decision blocks have the following connection ports: + +- One input port located on the top of the block +- One output port located on the right the block +- One output port located on the bottom of the block + +An [execution][] passes through the input port, executes the block, and based on the result of the execution moves to the input port of the block connected to the correct output port. + +### Exception Handling Blocks + +Exception Handling blocks are used to handle exceptions thrown within a [flow][]. + +Exceptions can be handled at different levels within a [flow][]; at the block level, the workspace level, and the flow level. For more information see [Handling Exceptions][]. + +#### Block Image + +{{< figure src="/images/editable/exception-handling-blocks.png" >}} + +- Exception Handling blocks have a pink background + +#### Connection Ports + +[Handle Block Exception blocks][] have the following connection ports: + +- One red exception input port located on the left of the block +- One red exception output port located on the right of the block if they can be [chained][] +- One output port located on the bottom of the block + +An [execution][] passes through the exception input port, executes the block, and if the [exception][] can be handled, moves to the input port of the block connected to the output port; if an exception cannot be handled the execution moves to the exception input port of the [exception handling block][Exception Handling Blocks] connected to the exception output port, for more information see [Chaining Block Exception Handling Blocks][chained]. + +[Handle Workspace Exception blocks][] have the following connection ports: + +- One output port located on the bottom of the block + +[Handle Flow Exception blocks][] have no connection ports. + +### Workspace Blocks + +Workspace blocks are used to group logic and actions within a [flow][] in order to reduce the complexity and make the flow easier to maintain. For more information see [Workspaces][]. + +Unhandled exceptions thrown within a workspace can be handled by connecting a [Handle Block Exception block][Handle Block Exception blocks] to the red output port of the Workspace block. + +#### Block Image + +{{< figure src="/images/workspace-blocks.svg" >}} + +- Workspace blocks are rectangle shaped +- Workspace blocks are larger than [Action Blocks][] +- Workspace blocks have a pale blue background + +#### Connection Ports + +Workspace Blocks have the following connection ports: + +- One input port located on the top of the block +- One output port located on the bottom of the block +- One red exception output port located on the right of the block + +An [execution][] passes through the input port and executes the workspace block, and if no unhandled [exception][] occurs, moves to the input port of the block connected to the output port; if an unhandled exception occurs the execution moves to the exception input port of the [exception handling block][Exception Handling Blocks] connected to the exception output port. + +### Block Properties + +Blocks are configured using [Block Properties][]. Properties pass data to the block which is then used to perform an action, or branch based on a condition within a [flow][]. + +There are three types of block properties: + +- [Input][] +- [Output][] +- [InputOutput][] + +Most blocks share [Common Properties][] such as a description for the block. Some blocks have [Advanced Properties][] that do not normally need to be configured but allow for more advanced scenarios. + +For further information, see [Block Properties][]. + +### Block Connections + +Block connections help determine the order blocks will be executed in a flow, an execution moves through the flow sequentially + +An execution moves from one connected block to another, depending on the logic of the block. Blocks can be connected to each other through the use of connection ports. + +There are four types of connections ports + +- Input Ports - act as the entry point of a block, output ports from one or more other blocks can be connected to an input port +- Output Ports - act as the exit point of a block, output ports can only be connected to an input port of one other block +- Exception Input Ports - act as the entry point of an exception handling block, exception output ports from one or more other blocks can be connected to an exception input port +- Exception Output Ports - act as the exit point of a block when an exception is thrown, exception output ports can only be connected to an exception input port of one exception handling block + +## Exceptions within a Block + +Exceptions thrown within the execution of a block can be handled by connecting a [Handle Block Exception block][Handle Block Exception blocks] to the red output port. If there is no [Handle Block Exception block][Handle Block Exception blocks] that can handle the exception then it will be passed to the workspace level to be handled. + +For further information, see [Handling Exceptions within a Block][]. + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Block Properties][] +- [Executions][] +- [Exceptions][] + +### Related Blocks + +- [All Blocks][Blocks] + +### External Documentation + +None + +[Flow Control Blocks]: {{< ref "#flow-control-blocks" >}} +[Action Blocks]: {{< ref "#action-blocks" >}} +[Decision Blocks]: {{< ref "#decision-blocks" >}} +[Exception Handling Blocks]: {{< ref "#exception-handling-blocks" >}} +[Workspace Blocks]: {{< ref "#workspace-blocks" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[exception]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.WhatIsAnException.MainDoc" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[chained]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.ChainingExceptions" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Advanced Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Common Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.MainDoc" >}} +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Handling Exceptions within a Block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.HandlingExceptionsWithinABlock.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Flow Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.MainDoc" >}} +[Handle Workspace Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/_index.md new file mode 100644 index 000000000..5e6b8dc14 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/_index.md @@ -0,0 +1,6 @@ +--- +title: "Data Types" +linkTitle: "Data Types" +description: "Information regarding what a data type is, and the difference between basic and complex data types." +weight: 400 +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/generics.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/generics.md new file mode 100644 index 000000000..eee267f88 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/generics.md @@ -0,0 +1,38 @@ +--- +title: "Generics" +linkTitle: "Generics" +description: "Information regarding generic data types." +weight: 100 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/null-and-nullable-types.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/null-and-nullable-types.md new file mode 100644 index 000000000..ce35d9b02 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/null-and-nullable-types.md @@ -0,0 +1,46 @@ +--- +title: "Null and Nullable Types" +linkTitle: "Null and Nullable Types" +description: "Information regarding null and nullable data types." +weight: 200 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Null + +TODO + +## Nullable Types + +TODO + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/what-is-a-data-type.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/what-is-a-data-type.md new file mode 100644 index 000000000..147403d92 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/data-types/what-is-a-data-type.md @@ -0,0 +1,95 @@ +--- +title: "What is a Data Type?" +linkTitle: "What is a Data Type?" +description: "Information regarding what a data type is, basic and complex data types and their differences." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Overview of a data type +- Difference between Value (value types cannot be null, and have a default value that is not null e.g. int is `0`) and Reference Data Types (reference types can be null and have a null default value) +- Difference between Basic and Complex Data Types + +## Value Types + +TODO: + +- Explain what a value type is, and how it can be used +- Check Set Variable block and how Value Types work within the block + - Setting a new variable to an already existing value type will cause them to be separate instances of the value +- The Copy Object block can be used to make a copy of a value type (value types always have a different reference) + +## Reference Types + +TODO: + +- Explain what a reference type is, and how it can be used +- This is referenced by the Set Variable block + - Set Variable block is used to set ($)List[0] + - When adding `($)Reference` to `($)List`, the actual reference is added (not a copy) + - Setting value of `($)List1` to `($)List2` will cause them to have the same reference. Changes to `($)List1` are reflected in `($)List2` +- The Copy Object block can be used to make a copy of a type with a different reference + +## Basic Data Types + +TODO: + +- Explain what a basic data type is +- Table of Basic Data Types + - Columns - Data Type Name, Value/Reference Type + - Strings are a basic data type but are also a reference type. + +## Complex Data Types + +TODO: + +- Explain what a complex data type is and what makes a data type complex +- Includes Complex and Collections (Lists, Dictionaries, structures, etc) +- Object +- Dynamic +- Object vs Dynamic + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +- [All Data Types][Data Type] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +TODO: + +- [Value Types][] +- [Reference Types][] +- [Builtin Types][] +- [Default Values][] + +[Reference Types]: {{< url path="MSDocs.CSharp.ReferenceTypes" >}} +[Value Types]: {{< url path="MSDocs.CSharp.ValueTypes" >}} +[Builtin Types]: {{< url path="MSDocs.CSharp.BuiltinTypes" >}} +[Default Values]: {{< url path="MSDocs.CSharp.DefaultValues" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Data Type]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/_index.md new file mode 100644 index 000000000..891d55a14 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/_index.md @@ -0,0 +1,7 @@ +--- +title: "Exceptions" +linkTitle: "Exceptions" +description: "Information regarding what an exceptions is, handling exceptions, and throwing exceptions." +weight: 600 +--- + diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/handling-exceptions.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/handling-exceptions.md new file mode 100644 index 000000000..447ee7512 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/handling-exceptions.md @@ -0,0 +1,186 @@ +--- +title: "Handling Exceptions" +linkTitle: "Handling Exceptions" +description: "Information regarding handling exceptions at the block, workspace and flow level." +weight: 100 +--- + +# {{% param title %}} + +## Summary + +Exceptions within a flow can be handled at the following levels: + +- The [block level][] (Highest Priority) +- The [workspace level][] +- The [flow level][] (Lowest Priority) + +## Handling Exceptions at the Block level + +{{< figure src="/images/block-exception.gif" >}} + +Exceptions thrown within the [execution][] of a [block][] can be handled by connecting a [Handle Block Exception block][Handle Block Exception blocks] to the red exception output port. These blocks allow for specific [match criteria][] to be provided; if an exception matches the criteria it will be handled by the block and can be [saved to a variable][block saved to a variable], otherwise, it will be passed to the next [chained][] exception handling block. This process repeats until the exception is either handled or there are no more blocks in the chain; if the exception is not handled at this level it is passed up to the [workspace level][]. + +### Matching Exceptions + +[Handle Block Exception blocks][] can be configured to handle exceptions that match specific criteria (e.g. The Exception Type or Message contains matching text). If an exception matches the criteria, the exception is handled, [saved to a variable][block saved to a variable] if provided, and the [execution][] moves to the block connected to the output port; if the exception does not match the criteria the execution moves to the next [chained][] exception handling block. + +### Chaining Block Exception Handling Blocks + +{{< figure src="/images/chained-exception.gif" >}} + +[Handle Block Exception blocks][] can be chained together by connecting the red exception output port of one [block][] to the red exception input port of another. When an exception is not handled, it will be passed to the next chained exception handling block. This process repeats until the exception is either handled or there are no more blocks in the chain; if the exception is not handled at this level it is passed up to the [workspace level][]. + +The [Handle Block Exception][] block can be used to handle all exceptions. This block does not have an exception output port and therefore ends the chain. + +### Saving the Block Exception + +[Handle Block Exception blocks][] can be used to save the handled exception to a [variable][]. If it is not necessary to save the exception to a variable, it may be [discarded][] by setting the block's Exception [property][] to use the built-in discard variable `($)_`. + +## Handling Exceptions at the Workspace level + +{{< figure src="/images/workspace-exception.gif" >}} + +Exceptions not handled at the [block level][] are passed up to the workspace level. + +If an unhandled exception occurs in a [Nested Workspace][] where a [Handle Workspace Exception][] block exists: + +- The exception will be passed to the [Handle Workspace Exception][] block +- The exception will be handled and can be [saved to a variable][workspace saved to a variable] +- The [execution][] will move to the [block][] connected to the output port of the [Handle Workspace Exception][] block + +If an unhandled exception occurs in a [Nested Workspace][] where a [Handle Workspace Exception][] block does not exist: + +- The exception will be rethrown by the [Workspace block][] the [workspace][] belongs to +- This process repeats until the exception is handled at the [block level][] or workspace level, or reaches the [Top-Level Workspace][] + +If an unhandled exception occurs in or reaches the [Top-Level Workspace][], and is not handled by any [Handle Block Exception blocks][] or the [Handle Workspace Exception][] block, it will be passed up to the [flow level][]. + +Please note that there are a number of [restrictions][Restrictions Handle Workspace Exception] when using the [Handle Workspace Exception][] block. + +### Saving the Workspace Exception + +The [Handle Workspace Exception][] block can be used to save the handled exception to a [variable][]. If it is not necessary to save the exception to a variable, it may be [discarded][] by setting the block's Exception [property][] to use the built-in discard variable `($)_`. + +## Handling Exceptions at the Flow level + +{{< figure src="/images/flow-exception.gif" >}} + +If an unhandled exception occurs in or reaches the [Top-Level Workspace][], and is not handled at the [block level][] or [workspace level][], it will be passed up to the flow level, where: + +- The exception will be passed to the [Handle Flow Exception][] block +- The exception will be handled and can be saved to a [variable][] +- The [execution][] will enter the [Handle Flow Exception][] block's [workspace][] +- The [execution][] will end after the [Handle Flow Exception][] block's [workspace][] has completed + +The [Handle Flow Exception][] block is automatically added to the [Top-Level Workspace][] when a new [flow][] is created, there are [restrictions][Restrictions Handle Flow Exception] that apply to this block. + +The [Handle Flow Exception][] block it has its own [workspace][], which can access its own [variables][variable] and those defined at the [scope][] of the [Top-Level Workspace][]. + +The logic contained within the [Handle Flow Exception][] workspace must end the execution using an [End Flow][] block. By default, this workspace contains a [Start Workspace][] block connected to an [End Flow][] block, which will cause the flow to end without error. + +### Handling Exceptions in the Handle Flow Exception block + +Exceptions that occur within the [workspace][] of the [Handle Flow Exception][] block can be handled at the [block level][] and [workspace level][]. If an exception is not handled, the [execution][] will end with a status of Error. + +{{< figure src="/images/flow-error-status.png" >}} + +### Saving the Flow Exception + +The [Handle Flow Exception][] block can be used to save the handled exception to a [variable][]. If it is not necessary to save the exception to a variable, it may be [discarded][] by setting the block's Exception [property][] to use the built-in discard variable `($)_`. + +## Remarks + +### Known Limitations + +#### The Top-Level Workspace cannot contain a Handle Workspace Exception block + +The [Top-Level Workspace][] cannot contain a [Handle Workspace Exception][] block; if one is added, it will be reported when trying to validate the [flow][]. For more information see [Validating a Flow in Development][] and [Validating a Flow in Production][]. + +Any unhandled exceptions thrown on the Top-Level Workspace will be handled by the [Handle Flow Exception][] block. + +In the future this may change. + +#### A Nested Workspace cannot contain more than one Handle Workspace Exception block + +A [Nested Workspace][] cannot contain more than one [Handle Workspace Exception][] block; if more than one is added, it will be reported when trying to validate the [flow][]. For more information see [Validating a Flow in Development][] and [Validating a Flow in Production][]. + +In the future this may change. + +#### Enforced restrictions to prevent infinite recursion + +For each [execution][] of a [workspace][], the [Handle Workspace Exception][] block will only handle the first unhandled exception within its workspace, this is to prevent infinite recursion within the [flow][]. + +For more information see [Handling Exceptions at the Workspace level][workspace level]. + +In the future this may change. + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Workspaces][] +- [Variables][] +- [Executions][] + +### Related Data Types + +- [All Exceptions][] + +### Related Blocks + +- [Handle Block Exception blocks][] +- [Handle Workspace Exception][] +- [Handle Flow Exception][] +- [Workspace][Workspace block] +- [Start Workspace][] +- [End Flow][] + +### External Documentation + +None + +[block level]: {{< ref "#handling-exceptions-at-the-block-level" >}} +[chained]: {{< ref "#chaining-block-exception-handling-blocks" >}} +[block saved to a variable]: {{< ref "#saving-the-block-exception" >}} +[workspace saved to a variable]: {{< ref "#saving-the-workspace-exception" >}} +[match criteria]: {{< ref "#matching-exceptions" >}} +[workspace level]: {{< ref "#handling-exceptions-at-the-workspace-level" >}} +[flow level]: {{< ref "#handling-exceptions-at-the-flow-level" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} +[Top-Level Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.TopLevelWorkspace" >}} +[Nested Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.NestedWorkspaces" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} +[discarded]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.DiscardingOutputs" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} +[Validating a Flow in Development]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment.ValidatingAFlow" >}} +[Validating a Flow in Production]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInProduction.ValidatingAFlow" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[All Exceptions]: {{< url path="Cortex.Reference.Exceptions.MainDoc" >}} + +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} + +[Workspace block]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.MainDoc" >}} +[Start Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.StartWorkspace.StartWorkspace.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} +[Handle Block Exception blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.MainDoc" >}} +[Handle Block Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockException.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Restrictions Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.BlockRestrictions" >}} +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} +[Restrictions Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.BlockRestrictions" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/throwing-exceptions.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/throwing-exceptions.md new file mode 100644 index 000000000..e77db146c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/throwing-exceptions.md @@ -0,0 +1,55 @@ +--- +title: "Throwing Exceptions" +linkTitle: "Throwing Exceptions" +description: "Information regarding throwing an exception within a flow, and scenarios when it is useful to throw an exception." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +A developer can throw an exception as part of a [flow][]. + +Scenarios where throwing exceptions is useful include: + +- A developer throwing a new exception when a flow reaches a state where it cannot complete its defined functionality +- A developer enriching an exception that has already been thrown to provide more clarity and/or detail +- A developer rethrowing an exception to propagate the exception to the caller; typically this can be useful when [calling another flow][] + +For information about throwing an exception, please see the: + +- [Throw New Flow Exception][] block +- [Rethrow Exception][] block + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] + +### Related Blocks + +- [Throw New Flow Exception][] +- [Rethrow Exception][] + +### External Documentation + +None + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} + +[Rethrow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.RethrowException.RethrowException.MainDoc" >}} + +[Throw New Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.ThrowException.ThrowNewFlowException.MainDoc" >}} +[calling another flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.CallingOtherFlows.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/what-is-an-exception.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/what-is-an-exception.md new file mode 100644 index 000000000..14c3a64e0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/exceptions/what-is-an-exception.md @@ -0,0 +1,110 @@ +--- +title: "What is an Exception?" +linkTitle: "What is an Exception?" +description: "Information regarding the anatomy of an exception, and properties accessible on an exception." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +An exception is thrown during an [execution][] when an issue is encountered whilst executing a [flow][]. Exceptions can occur for a number of reasons, such as: + +- Exceptions thrown by a [block][], these can be found in the relevant documentation for that [block][All Blocks] (e.g. A duplicate key is added to a [Dictionary][] using the [Add Item With Key][] block) +- Developer thrown [exceptions][Throwing Exceptions] (e.g. A developer enriches an exception that has already been thrown to provide a more detailed message) +- Issues with third-party systems (e.g. A third-party system experiences an error) +- Issues with network connectivity (e.g. A target machine is inaccessible) +- Issues with permissions (e.g. The execution does not have permission to read a file) +- Issues with the environment (e.g. The software installed on a target machine is incorrect) + +An exception contains details of what caused the issue, for more information see [Anatomy of an Exception][]. + +An exception can be handled in different ways depending on where the exception occurred. For more information see [Handling Exceptions][]. + +## Anatomy of an Exception + +{{< figure src="/images/exception-in-viewer.PNG" >}} + +Data within an exception can be accessed using properties. + +The following properties are found on all exceptions: + +| Property | Notes | Example | +|----------|-------|---------| +| Exception Type | The type of the exception | `PropertyNullException` +| Message | The exception message, providing information about the exception that occurred. This typically includes the cause of the exception, possible resolutions, and any related information. What is included in an exception's message can be found in the relevant documentation for that [exception][Exceptions] | `'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 | Help link to aid with troubleshooting and resolution for the exception. There are three types of help links:

  • {{% ctx %}} - Help links direct to material within the {{% ctx %}} Product Portal. This documentation is written and maintained by {{% ctx %}} and contains information directly related to the {{% ctx %}} product.
  • External - Help links direct to externally hosted material about the exception. This documentation is not written or maintained by {{% ctx %}}.
  • Custom - Help links are generated by flow developers during the design and development of flows. These help links are configured in the [Throw New Exception][] block, and can link to any resource applicable to the exception.
| `https://docs.wearecortex.com/docs/2023.5/reference/exceptions/common/property/property-null-exception/` | + +The following properties are found on many exceptions: + +| Property | Notes | Example | +|----------|-------|---------| +| Category | The category of the exception, which is used to categorise an exception if there are multiple reasons that the exception can occur. | [InfiniteLoopException][InfiniteLoopException: Category] has one category, `"Increment"` | +| 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. | [InfiniteLoopException][InfiniteLoopException: Error Code] has three error codes, `InfiniteLoopErrorCode.IncrementIsZero (100)`, `InfiniteLoopErrorCode.IncrementIsNegative (101)`, and `InfiniteLoopErrorCode.IncrementIsPositive (102)` | +| Inner Exception | Contains the exception that caused this exception, if any. This property is always accessible but will only be visible in the [Exceptions Viewer][] when it contains data. | `{"ExceptionType": "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/"}` | + +For more information regarding what properties are accessible on an exception, see the relevant documentation for that [exception][Exceptions]. + +## Remarks + +### Known Limitations + +#### Carriage Return and Line Feed Characters + +Carriage Return and Line Feed characters within an exception are supported but will be displayed or written as `\r`, `\n`, or `\r\n`. + +In future this limitation may be removed. + +#### Copying Exception Text + +The [Exceptions Viewer][] currently does not support traditional copy functionality. A workaround is to highlight the text, then click and drag into another text editor. + +In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Executions][] + +### Related Data Types + +- [All Exceptions][Exceptions] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Anatomy of an Exception]: {{< ref "#anatomy-of-an-exception" >}} + +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[Throwing Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.ThrowingExceptions.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Exception Blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.MainDoc" >}} +[Throw New Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.ThrowException.ThrowNewFlowException.MainDoc" >}} +[Add Item With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.AddItem.AddItemWithKey.MainDoc" >}} + +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Exceptions.MainDoc" >}} +[InfiniteLoopException: Category]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.Category" >}} +[InfiniteLoopException: Error Code]: {{< url path="Cortex.Reference.Exceptions.Loops.InfiniteLoopException.ErrorCode" >}} + +[Exceptions Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.ExceptionsViewer" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/_index.md new file mode 100644 index 000000000..370e98eae --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/_index.md @@ -0,0 +1,6 @@ +--- +title: "Executions" +linkTitle: "Executions" +description: "Information regarding what an execution is, starting executions, execution variables, exceptions thrown during an execution, and execution metadata." +weight: 500 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-development.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-development.md new file mode 100644 index 000000000..f1ceee546 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-development.md @@ -0,0 +1,229 @@ +--- +title: "Executions in Development" +linkTitle: "Executions in Development" +description: "Information regarding working with executions in development (i.e. {{% ctx %}} Studio)." +weight: 100 +--- + +# {{% param title %}} + +## Summary + +Whilst debugging a flow, each execution is represented by a [token][] that moves through the [flow][], showing which [block][] is currently being executed. + +A [flow][] can be debugged in [{{% ctx %}} Studio][CORTEX Studio] by clicking the [Start an execution][] button or by making an [API call][API call: CORTEX Studio] to [{{% ctx %}} Studio][CORTEX Studio], [providing input variables][Providing Input Variables] to the flow, if required; this will [validate the flow][Validating a Flow] and then begin an execution. + +The following parameters can be specified: + +- Show execution on workspace - when this is `true`, the token will be shown at every step throughout the [flow][], otherwise the token will only be shown when the execution [pauses][Paused], hits a [breakpoint][], or an exception occurs when `Break on exception` is `true` +- Break on exception - when this is `true` the execution will [pause][Paused] when an exception occurs + +## Providing Input Variables + +Any flow that has [Input Variables][] defined requires them to be provided when debugging, these may be provided to a flow in the following ways: + +- From [{{% ctx %}} Studio][CORTEX Studio] using the [Inputs Property][] in the [Settings Editor][] +- From an [HTTP request][HTTP request: CORTEX Studio] using the inputVariables in the body of the request + +## Retrieving Output Variables + +Any flow that has [Output Variables][] defined can have those variables retrieved after the execution has completed by using the outputVariables in the body of the [HTTP response][HTTP response: CORTEX Studio]. + +## Validating a Flow + +The [flow][] is validated before it's debugged, if this is successful an execution will begin. + +If there are any issues with the flow then the execution will not start and details of what needs to be resolved will be returned. If the flow was debugged by clicking the [Start an execution][] button, then entries will be displayed in the [Messages Grid][]; if it was debugged by making an [HTTP request][HTTP request: CORTEX Studio] to [{{% ctx %}} Studio][CORTEX Studio], then a 400 Bad Request is returned. + +For a complete list see [Validation][] messages. + +## Selecting an Execution + +One or more executions can be selected within [{{% ctx %}} Studio][CORTEX Studio] by clicking on their [token][], or selecting them using the [Executions Grid][]. This allows: + +- [Interacting with an Execution][] +- [Viewing an Execution's Variables][] +- [Viewing an Execution's Exceptions][] + +## Interacting with an Execution + +Once executions are [selected][Selecting an Execution] in [{{% ctx %}} Studio][CORTEX Studio] they can be interacted with in the following ways: + +- [Paused][] +- [Stepped][] +- [Continued][] +- [Stopped][] + +### Set Next Block to Execute + +[Set Next Block to Execute][] allows a developer to choose which [block][] will be executed next for the selected execution, even if this block is not connected to the [flow][]. + +Examples of what this can be used to do whilst debugging include: + +- Retrying a block due to a transient exception such as network connectivity +- Retrying a block after using [Edit and Continue][Edit and Continue an Execution] to fix an incorrectly configured block +- Skipping over functionality that is not yet working +- Skipping to specific functionality within the flow in order to test it +- Running logic that is not part of the flow (e.g. running a clean up script to reset any external data sources for the next execution of the flow) + +Currently, Set Next Block to Execute is not available when [multiple executions are selected][], or the [block and execution are on different workspaces][]. + +### Edit and Continue an Execution + +[Edit and Continue][] allows a developer to pause all executions, and make changes to the [flow][] before continuing debugging. + +Examples of what this can be used to do whilst debugging include: + +- Making changes such as adding, updating and removing: [blocks][block], [connections][], [variables][variable] +- Fixing an incorrectly configured block + +Currently when using Edit and Continue, it is not possible to [directly change the value of a variable without using a block][]. + +## Viewing an Execution's Variables + +When debugging a [flow][] in [{{% ctx %}} Studio][CORTEX Studio], [selecting an execution][Selecting an Execution] will display all initialised [variables][variable] that are in [scope][] in the [Variables Viewer][]. + +To see the data in a variable, select the variable in the [Variables Viewer][] and the data will be presented in the [Variable Details Viewer][]. If the data is large enough to negatively affect the performance of [{{% ctx %}} Studio][CORTEX Studio] it will not be displayed unless the [Load Value Button][] is clicked. + +## Viewing an Execution's Exceptions + +When debugging a [flow][] in [{{% ctx %}} Studio][CORTEX Studio], [selecting an execution][Selecting an Execution] will display all [exceptions][exception] that have been thrown for that execution in the [Exceptions Viewer][]. + +In future, it will be possible to navigate to the block that caused the exception. + +## Handling an Execution's Exceptions + +Exceptions thrown by an execution can be handled at any level within a flow. + +Exceptions can be handled: + +- At the [block][] level; for further information, see [Handling Exceptions within a Block][] +- At the [workspace][] level; for further information, see [Handling Exceptions within a Workspace][] +- At the [flow][] level; for further information, see [Handling Exceptions within a Flow][] + +If an exception occurs within the workspace of the [Handle Flow Exception][] block and is not handled, the execution will end with a status of Error. + +{{< figure src="/images/flow-error-status.png" >}} + +## Logs Generated + +There are two ways that logs are generated while debugging a [flow][], they are: + +- Automatically generated by the [Execution Service][Execution Service] +- Developer generated by using the [Log Event][] block + +## Remarks + +### Known Limitations + +#### Updating a Variable's value is not possible without using a Block + +When using [Edit and Continue][], it is not possible to directly change the value of a [variable][] without using a [block][]. + +In future this limitation may be removed. + +#### Set Next Block to Execute not available when multiple Executions are selected + +It is not possible to use [Set Next Block to Execute][] when there are multiple executions selected on the same [workspace][]. + +In future this limitation may be removed. + +#### Set Next Block to Execute not available when the Block and Execution are on different Workspaces + +It is not possible to use [Set Next Block to Execute][] when the selected execution is not on the same [workspace][] as the [block][] being set next to execute. + +In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Variables][] +- [Data Types][] +- [Exceptions][] +- [Messages][] + +### Related Data Types + +- [All Data Types][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Providing Input Variables]: {{< ref "#providing-input-variables" >}} +[Validating a Flow]: {{< ref "#validating-a-flow" >}} +[Interacting with an Execution]: {{< ref "#interacting-with-an-execution" >}} +[Viewing an Execution's Variables]: {{< ref "#viewing-an-executions-variables" >}} +[Viewing an Execution's Exceptions]: {{< ref "#viewing-an-executions-exceptions" >}} +[Selecting an Execution]: {{< ref "#selecting-an-execution" >}} +[Edit and Continue an Execution]: {{< ref "#edit-and-continue-an-execution" >}} +[multiple executions are selected]: {{< ref "#set-next-block-to-execute-not-available-when-multiple-executions-are-selected" >}} +[block and execution are on different workspaces]: {{< ref "#set-next-block-to-execute-not-available-when-the-block-and-execution-are-on-different-workspaces" >}} +[directly change the value of a variable without using a block]: {{< ref "#updating-a-variables-value-is-not-possible-without-using-a-block" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[connections]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.BlockConnections" >}} +[Handling Exceptions within a Block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.HandlingExceptionsWithinABlock.MainDoc" >}} + +[Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[exception]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.WhatIsAnException.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} +[Handling Exceptions within a Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.HandlingExceptionsWithinAFlow.MainDoc" >}} + +[Messages]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.MainDoc" >}} +[message]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.WhatIsAMessage.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} +[Input Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} +[Output Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} +[Handling Exceptions within a Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.HandlingExceptionsWithinAWorkspace.MainDoc" >}} +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Log Event]: {{< url path="Cortex.Reference.Blocks.Logs.LogEvent.LogEvent.MainDoc" >}} + +[All Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} + +[API call: CORTEX Studio]: {{< url path="Cortex.Reference.Apis.Studio.MainDoc" >}} +[HTTP request: CORTEX Studio]: {{< url path="Cortex.Reference.Apis.Studio.MainDoc" >}} +[HTTP response: CORTEX Studio]: {{< url path="Cortex.Reference.Apis.Studio.MainDoc" >}} + +[Execution Service]: {{< url path="Cortex.Reference.Logs.CortexExecutionService.MainDoc" >}} +[Validation]: {{< url path="Cortex.Reference.Messages.Validation.MainDoc" >}} + +[CORTEX Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Set Next Block to Execute]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.SetNextBlockToExecute" >}} +[breakpoint]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.Breakpoints" >}} +[token]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.Executions" >}} +[Start an execution]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.StartAnExecution" >}} +[Edit and Continue]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.EditAndContinueAnExecution" >}} +[Exceptions Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.ExceptionsViewer" >}} +[Variable Details Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.VariableDetailsViewer" >}} +[Load Value Button]: {{< url path="Cortex.Guides.Studio.EastPanel.LoadValueButton" >}} +[Variables Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.VariablesViewer" >}} +[Settings Editor]: {{< url path="Cortex.Guides.Studio.EastPanel.SettingsEditor" >}} +[Inputs Property]: {{< url path="Cortex.Guides.Studio.EastPanel.InputsProperty" >}} +[Executions Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.ExecutionsGrid" >}} +[Paused]: {{< url path="Cortex.Guides.Studio.SouthPanel.PausingAnExecution" >}} +[Stepped]: {{< url path="Cortex.Guides.Studio.SouthPanel.SteppingAnExecution" >}} +[Continued]: {{< url path="Cortex.Guides.Studio.SouthPanel.ContinuingAnExecution" >}} +[Stopped]: {{< url path="Cortex.Guides.Studio.SouthPanel.StoppingAnExecution" >}} +[Messages Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.MessagesGrid" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-production.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-production.md new file mode 100644 index 000000000..752dca900 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/executions-in-production.md @@ -0,0 +1,121 @@ +--- +title: "Executions in Production" +linkTitle: "Executions in Production" +description: "Information regarding working with executions in production (i.e. API Gateway Service)." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +A [flow][] can be started in Production by making an [API call][API call: API Gateway] to the [API Gateway Service][], [providing input variables][Providing Input Variables] to the flow, if required; this will [validate the flow][Validating a Flow] and then begin an execution. + +## Providing Input Variables + +Any flow that has [Input Variables][] defined can have those variables provided by using the inputVariables in the body of the [HTTP request][HTTP request: API Gateway Service]. + +## Retrieving Output Variables + +Any flow that has [Output Variables][] defined can have those variables retrieved after the execution has completed by using the outputVariables in the body of the [HTTP response][HTTP response: API Gateway Service] + +## Validating a Flow + +The [flow][] is validated before it's started, if this is successful an execution will begin. + +If there are any issues with the flow then the execution will not start and details of what needs to be resolved will be returned. If the flow was started by making an [HTTP request][HTTP request: API Gateway Service] to the [API Gateway Service][], then a 400 Bad Request is returned. + +For a complete list see [Validation][] messages. + +## Handling an Execution's Exceptions + +Exceptions thrown by an execution can be handled at any level within a flow. + +Exceptions can be handled: + +- At the [block][] level; for further information, see [Handling Exceptions within a Block][] +- At the [workspace][] level; for further information, see [Handling Exceptions within a Workspace][] +- At the [flow][] level; for further information, see [Handling Exceptions within a Flow][] + +If an exception occurs within the workspace of the [Handle Flow Exception][] block and is not handled, the execution will end and then a 500 Internal Server Error is returned. + +## Logs Generated + +There are two ways that logs are generated while executing a [flow][] in Production, they are: + +- Automatically generated by the [API Gateway Service][API Gateway Service: Logs] +- Developer generated by using the [Log Event][] block + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Variables][] +- [Data Types][] +- [Exceptions][] +- [Messages][] + +### Related Data Types + +- [All Data Types][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Providing Input Variables]: {{< ref "#providing-input-variables" >}} +[Validating a Flow]: {{< ref "#validating-a-flow" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Handling Exceptions within a Block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.HandlingExceptionsWithinABlock.MainDoc" >}} + +[Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[exception]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.WhatIsAnException.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} +[Handling Exceptions within a Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.HandlingExceptionsWithinAFlow.MainDoc" >}} + +[Messages]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.MainDoc" >}} +[message]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.WhatIsAMessage.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} +[Input Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} +[Output Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} +[Handling Exceptions within a Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.HandlingExceptionsWithinAWorkspace.MainDoc" >}} +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Log Event]: {{< url path="Cortex.Reference.Blocks.Logs.LogEvent.LogEvent.MainDoc" >}} + +[All Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} + +[API Gateway Service: Logs]: {{< url path="Cortex.Reference.Logs.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} + +[Validation]: {{< url path="Cortex.Reference.Messages.Validation.MainDoc" >}} + +[API Gateway Service]: {{< url path="Cortex.Reference.Apis.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[API call: API Gateway]: {{< url path="Cortex.Reference.Apis.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[HTTP request: API Gateway Service]: {{< url path="Cortex.Reference.Apis.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[HTTP response: API Gateway Service]: {{< url path="Cortex.Reference.Apis.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/what-is-an-execution.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/what-is-an-execution.md new file mode 100644 index 000000000..24b5b691f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/executions/what-is-an-execution.md @@ -0,0 +1,148 @@ +--- +title: "What is an Execution?" +linkTitle: "What is an Execution?" +description: "Information regarding the anatomy of an execution." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +An execution represents a running instance of a [flow][], the execution moves through the flow sequentially executing each [block][] saving any outputs to [variables][variable]. A flow can have one or more executions running at any time, each with their own variables. + +- See [Executions in Development][] for more information regarding working with executions in [{{% ctx %}} Studio][CORTEX Studio]. +- See [Executions in Production][] for more information regarding running executions in the [Execution Service][]. + +## Anatomy of an Execution + +{{< figure src="/images/execution-in-grid.PNG" >}} + +| Property | Notes | Example | +|-------------------|------------------------------------------------------------|-----------------------------------------------------------| +| Status Icon | The Icon representing the current Status of the execution | A list of [statuses][Execution Status] can be found below | +| Started At | The date and time that the execution was started | `6 Sep 2022 09:27:45` | +| Updated At | The date and time of the last update for the execution | `6 Sep 2022 09:27:46` | +| Status | The status of the execution | A list of [statuses][Execution Status] can be found below | +| Block Type | The block the execution is currently on | `Set Variable` | +| Block Description | The description of the block the execution is currently on | `Set Variable` | +| Workspace Name | The name of the workspace the execution is currently in | `Setup and Run Child-Flow` | +| Flow Name | The name of the flow the execution is currently running | `Parent-Flow` | + +When a [flow][] starts the execution of a child flow using the [Run Flow][] block, any child executions will be shown within a tree in the [Executions Grid][], for example: + +{{< figure src="/images/child-execution-in-grid.PNG" >}} + +### Execution Status + +| Status | Description | +|-----------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Running | The execution is currently executing | +| Pausing | The execution is in the process of pausing - e.g. a long running block may have to finish before the execution is paused | +| Paused | The execution is paused on top of a block - before the block starts to execute | +| | The execution is paused at a breakpoint on top of a block - before the block starts to execute | +| | The execution is paused on the output port of a block - after the block has executed but before the execution has selected which block is next | +| Exception | The execution is paused on the exception output port - after the block has thrown an exception when `break on exception` is turned on | +| Stopping | The execution is in the process of stopping - e.g. a long running block may have to finish before the execution is stopped | +| Stopped | The execution has ended after having been manually stopped | +| Ended | The execution has ended normally | +| Error | The execution has ended after having thrown an exception that was not handled | + +## Execution Context + +Executions have their own context that contains specific information about the current execution. This can be accessed via the built-in `_executionContext` [variable][] and currently contains the following properties: + +- [Initiator][] +- [Extensions][] + +### Initiator + +The initiator is a read-only property that contains the following information about the user that initiated the execution: + +- `Name`: The name of the user that initiated the execution. +- `AuthenticationType`: The authentication type of the user that initiated the execution. +- `IsAuthenticated`: A boolean value indicating if the user that initiated the execution is authenticated. This should always be `true`. +- `Claims`: A list of claims associated with the user that initiated the execution. + +The values can be accessed using [property expression][] or dictionary [index expressions][] syntax, as follows: + +```csharp +($)_executionContext.Initiator.Name +``` + +```csharp +($)_executionContext.Initiator["Name"] +``` + +### Extensions + +The `Extensions` property can be used to store additional information. This data will be accessible to all blocks within the execution, including child executions. + +A value can be added to the `Extensions` property using the [expression editor][], using the dictionary [index expressions][] syntax, for example: + +```csharp +($)_executionContext.Extensions["key"] = "value"; +``` + +The value can be accessed in the same way, for example: + +```csharp +($)_executionContext.Extensions["key"] +``` + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Variables][] + +### Related Data Types + +- [All Data Types][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Execution Status]: {{< ref "#execution-status" >}} +[Extensions]: {{< ref "#extensions" >}} +[Initiator]: {{< ref "#initiator" >}} + +[Executions in Development]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment.MainDoc" >}} +[Executions in Production]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInProduction.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[All Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} + +[CORTEX Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Executions Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.ExecutionsGrid" >}} + +[Execution Service]: {{< url path="Cortex.Reference.Apis.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} + +[expression editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[index expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.IndexExpressions" >}} +[Property expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.PropertyExpressions" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/_index.md new file mode 100644 index 000000000..a313a26d3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/_index.md @@ -0,0 +1,6 @@ +--- +title: "Flows" +linkTitle: "Flows" +description: "Information regarding what a flow is, how to call other flows and handling exceptions within a flow." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/calling-other-flows.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/calling-other-flows.md new file mode 100644 index 000000000..4ac55ad3f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/calling-other-flows.md @@ -0,0 +1,75 @@ +--- +title: "Calling Other Flows" +linkTitle: "Calling Other Flows" +description: "Information regarding calling, and passing data to, other flows." +weight: 100 +--- + +# {{% param title %}} + +## Summary + +A [flow][] may trigger the execution of another [flow][]. + +## Calling Another Flow + +A [flow][] can be called from another [flow][] in the following ways: + +- Using the [Run Flow][] block to trigger the execution of another flow directly +- Using the [Execute HTTP Request][] block to trigger a flow through the API Gateway service (this should only be used to call [flows][flow] published in a separate {{% ctx %}} Innovation platform) + +### Input Variables + +Sometimes [flows][flow] require data to be passed to them through the use of input variables (e.g. a flow used to log errors may require a file path for where the logs are saved). + +Input variables can be passed into flows in the following ways: + +- For the [Run Flow][] block, input variables are configured using the Inputs property; for more information see [Run Flow Example][] +- For the [Execute HTTP Request][] block, input variables are configured within the body of the HttpRequest; for more information see example of [Calling Another Flow][] + +### Output Variables + +Sometimes [flows][flow] may return data through the use of output variables (e.g. a flow used to interact with a database may return its results). + +Output variables are returned to the calling flow in the following ways: + +- For the [Run Flow][] block, output variables are saved to the Outputs property; for more information see [Run Flow Example][] +- For the [Execute HTTP Request][] block, output variables are returned within the ResponseBody of the HttpResponse property; for more information see example of [Calling Another Flow][] + +## Remarks + +### Known Limitations + +#### Flows can only be Called Synchronously + +Currently it is only possible to call other [flows][flow] synchronously; this means the calling flow will wait for the called flow to complete its [execution][] before continuing. + +In the future it will be possible to call flows asynchronously; this means the calling flow will continue after the called flow starts its [execution][] without waiting for the called flow to complete. + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Executions][] + +### Related Blocks + +- [Run Flow][] +- [Execute HTTP Request][] + +### External Documentation + +None + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} +[Run Flow Example]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.RunningAFlow" >}} +[Execute HTTP Request]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest.MainDoc" >}} +[Calling Another Flow]: {{< url path="Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest.CallingAnotherFlow" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/handling-exceptions-within-a-flow.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/handling-exceptions-within-a-flow.md new file mode 100644 index 000000000..f91fbc8b4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/handling-exceptions-within-a-flow.md @@ -0,0 +1,68 @@ +--- +title: "Handling Exceptions within a Flow" +linkTitle: "Handling Exceptions within a Flow" +description: "Information regarding handling exceptions at different levels within a flow." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +Exceptions within a flow can be handled at the following levels: + +- The [block level][] (Highest Priority) +- The [workspace level][] +- The [flow level][] (Lowest Priority) + +The [Handle Flow Exception][] block, which is located on the top-level [workspace][], handles any exceptions that are not handled at the [block][block level] or [workspace level][]. + +For more information, see [Handling Exceptions][]. + +## Remarks + +### Flow cannot be re-entered from the Handle Flow Exception Workspace + +Is it not possible to re-enter a flow once a [flow execution][] enters the [workspace][] of the [Handle Flow Exception][] block. + +### Known Limitations + +None + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Executions][] +- [Exceptions][] + +### Related Blocks + +- [Handle Flow Exception][] + +### External Documentation + +None + +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[block level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.BlockLevel" >}} +[flow level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.FlowLevel" >}} +[workspace level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.WorkspaceLevel" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[flow execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[Handle Workspace Exception block]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/what-is-a-flow.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/what-is-a-flow.md new file mode 100644 index 000000000..e56d20651 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/flows/what-is-a-flow.md @@ -0,0 +1,208 @@ +--- +title: "What is a Flow?" +linkTitle: "What is a Flow?" +description: "Information regarding the anatomy of a flow, starting flows, grouping logic within a flow, and handling exceptions within a flow." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +A flow is an object in [{{% ctx %}} Studio][CORTEX Studio] that contains the logic and actions (in the form of [blocks][] and [workspaces][]) that is able to be executed on a {{% ctx %}} platform. + +## Anatomy of a Flow + +There are two types of flows, which are used for different purposes: + +* [Process][] +* [Activity][] + +{{% alert title="Note" %}} +Prior to version 2024.9, there was a single type of flow named `Flow`. +As of 2024.9, `Flow` has been renamed to `Activity`. +{{% /alert %}} + +### Process + +Processes are a type of [Flow][] that can contain multiple [Activities][Activity] and are used to model high-level business processes. + +{{< figure src="/images/top-level-workspace-process.svg" title="Example Process" >}} + +* Processes flow from left to right +* Processes can call other processes +* Processes can call activities +* Processes only contain a subset of blocks as they are intended to model high-level business processes, not low-level implementation of tasks or actions +* Processes are optional an automation solution, but are useful for organizing and structuring the logic of a solution + +### Activity + +Activities are a type of [Flow][] that are used to model low-level tasks or actions. + +{{< figure src="/images/top-level-workspace-activity.svg" title="Example Activity" >}} + +* Activities flow from top to bottom +* Activities can call other activities +* Activities cannot call processes +* Activities contain all blocks as they are intended to model low-level tasks or actions +* Activities are required in an automation solution, as they are the building blocks of the solution + +## Composition of a Flow + +Flows are composed of the following: + +* [Workspace][Workspace ref] +* [Start Flow block][] +* [Action blocks][] +* [Decision blocks][Decision blocks ref] +* [Workspace blocks][] +* [End Flow block][] +* [Handle Flow Exception block][] + +### Workspace + +The [Top-Level Workspace][] within the flow. + +* Canvas on which blocks are placed and connected to create the flow logic +* See [Workspace][workspaces] + +### Start Flow block + +Identifies where the [flow execution][] will start. + +* Automatically created when the flow is created +* Cannot be deleted +* See [Start Flow][] block + +### Action blocks + +Performs a specific action. + +* Icon on block indicates the nature of the action +* See [Blocks][Reference Blocks] + +### Decision block + +Causes the [flow execution][] to branch, dependent on a condition. + +* See [Decision Blocks][Decision Blocks] + +### Workspace blocks + +Contains grouped flow logic. + +* See [Workspace][Workspace Block] block + +### End Flow block + +Ends the [flow execution][]. + +* Automatically created when the flow is created +* See [End Flow][] block + +### Handle Flow Exception block + +Handles [flow level exceptions][], thrown during the [flow execution][]. + +* Automatically created when the flow is created +* Cannot be deleted +* See [Handle Flow Exception][] block + +## Grouping Logic within a Flow + +All the logic of a flow can exist on the [Top-Level Workspace][], however, this can quickly become difficult to maintain and understand as the numbers of blocks increase. Blocks can be grouped into workspaces in order to reduce the complexity and make the flow easier to maintain. + +A [Workspace][Workspace Block] block can opened by double clicking it, showing its workspace canvas and the logic inside; this could include blocks for executing specific functions or other workspaces to help separate the logic of the flow further. + +For further information about [workspaces][workspace], see [Workspaces][workspaces]. + +## Starting a Flow Execution + +A [flow execution][flow execution] may be started by: + +* [Debugging][] a flow in [{{% ctx %}} Studio][CORTEX Studio] +* Triggering it by making an HTTP request from an external source (e.g. a web application or web hooks) +* Triggering it using the [Run Flow][] and [Run Flow Async][] block +* Triggering it using predefined events (future) (e.g. on receipt of an email) +* Scheduling it to execute at predetermined times + +## Exceptions within a Flow + +Flows support hierarchical exception handling at any level within the flow. + +Exceptions can be handled: + +* At the [block][] level; for further information, see [Handling Exceptions within a Block][] +* At the [workspace][] level; for further information, see [Handling Exceptions within a Workspace][] +* At the flow level; for further information, see [Handling Exceptions within a Flow][] + +## Remarks + +### Known Limitations + +#### Cannot have a Handle Workspace Exception block on the flow's Top-Level Workspace + +Currently, it is not possible to have a [Handle Workspace Exception][] block on the [Top-Level Workspace][] of a flow. In future this limitation may be removed. + +## See Also + +### Related Concepts + +* [Workspaces][workspaces] +* [Blocks][blocks] +* [Executions][] +* [Exceptions][] + +### Related Blocks + +* [Start Flow][] +* [End Flow][] +* [Run Flow][] +* [Run Flow Async][] +* [Handle Flow Exception][] +* [Handle Workspace Exception][] +* [Workspace][Workspace Block] + +### External Documentation + +None + +[Activity]: {{< ref "#activity" >}} +[Process]: {{< ref "#process" >}} +[Flow]: {{< ref "#summary" >}} + +[Start Flow block]: {{< ref "#start-flow-block" >}} +[Action blocks]: {{< ref "#action-blocks" >}} +[Decision blocks ref]: {{< ref "#decision-block" >}} +[Workspace blocks]: {{< ref "#workspace-blocks" >}} +[End Flow block]: {{< ref "#end-flow-block" >}} +[Handle Flow Exception block]: {{< ref "#handle-flow-exception-block" >}} +[Workspace ref]: {{< ref "#workspace" >}} + +[blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Handling Exceptions within a Block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.HandlingExceptionsWithinABlock.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[Handling Exceptions within a Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.HandlingExceptionsWithinAFlow.MainDoc" >}} +[flow level exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.FlowLevel" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[flow execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} +[workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[Handling Exceptions within a Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.HandlingExceptionsWithinAWorkspace.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} +[Top-Level Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.TopLevelWorkspace" >}} + +[Reference Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Decision Blocks]: {{< url path="Cortex.Reference.Blocks.Decisions.MainDoc" >}} +[Workspace Block]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.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" >}} +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} + +[CORTEX Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Debugging]: {{< url path="Cortex.Guides.Studio.Debugging.MainDoc" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} + +[Run Flow Async]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/_index.md new file mode 100644 index 000000000..978085070 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/_index.md @@ -0,0 +1,6 @@ +--- +title: "Messages" +linkTitle: "Messages" +description: "Information regarding what a message is." +weight: 700 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/what-is-a-message.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/what-is-a-message.md new file mode 100644 index 000000000..2baf3fed2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/messages/what-is-a-message.md @@ -0,0 +1,107 @@ +--- +title: "What is a Message?" +linkTitle: "What is a Message?" +description: "Information regarding the anatomy of a message, when a message will occur, and using messages to navigate to issues within a flow." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +When [Starting an Execution in Development][] using the [Start an execution][] button, the [flow][] will be [validated][]; if there are issues with the flow, [messages][] explaining the issues will be displayed in the [Messages Grid][]. + +Some examples of issues that can be raised are: + +- [Blocks][block] using undefined [variables][variable] +- [Blocks][block] using [variables][variable] with mismatched [data types][data type] +- [Input variables][] that have not been initialised + +For a complete list see [Validation][] messages. + +## Anatomy of a Message + +{{< figure src="/images/messages-grid.PNG" >}} + +Related messages are grouped by the component affected (e.g. A [block][], or the [Settings Editor][]) + +Each message row contains the following: + +| Property | Notes | +|----------|-------| +| Location | Path to the specific part of the component that has caused the issue | +| Summary | Short description of the issue | +| Details | Further information about the issue. This may also contain help for resolving the issue | + +## Navigating to the Location of an issue from a message + +Double clicking on a message within the [Messages Grid][] will navigate the browser to the affected location. + +## Remarks + +### Known Limitations + +#### It is not possible to navigate to a nested literal property from a message + +It is not possible to navigate to a nested literal property from a message, clicking the message will cause the browser to navigate to the last [property][] of the top-level [literal editor][] that contains the issue. + +In future this limitation may be removed. + +#### It is not possible to navigate to the Settings Editor from a message + +It is not possible to navigate to the [Settings Editor][] from a message, clicking the message will do nothing. + +In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Flows][] +- [Blocks][] +- [Variables][] +- [Data Types][] +- [Executions][] + +### Related Blocks + +- [All Blocks][] + +### Related Data Types + +- [All Data Types][] + +### External Documentation + +None + +[messages]: {{< ref "#anatomy-of-a-message" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} +[literal editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} +[Input variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} + +[Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} +[data type]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.MainDoc" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[Starting an Execution in Development]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment.MainDoc" >}} +[validated]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment.ValidatingAFlow" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[All Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} + +[Validation]: {{< url path="Cortex.Reference.Messages.Validation.MainDoc" >}} + +[Start an execution]: {{< url path="Cortex.Guides.Studio.MainDisplayArea.StartAnExecution" >}} +[Messages Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.MessagesGrid" >}} +[Settings Editor]: {{< url path="Cortex.Guides.Studio.EastPanel.SettingsEditor" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/_index.md new file mode 100644 index 000000000..f18e70787 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/_index.md @@ -0,0 +1,6 @@ +--- +title: "Variables" +linkTitle: "Variables" +description: "Information regarding what a variable is, using variables, and variable scopes." +weight: 300 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/using-variables.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/using-variables.md new file mode 100644 index 000000000..bfeff30e7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/using-variables.md @@ -0,0 +1,212 @@ +--- +title: "Using Variables" +linkTitle: "Using Variables" +description: "Information regarding using variables in the Variable and Expression editors." +weight: 200 +--- + +# {{% param title %}} + +## Summary + +There are a number of ways to use variables: + +- The [Variable Editor][Using Variables: Variable Editor] can be used to create and select variables +- The [Expression Editor][Using Variables: Expression Editor] can be used to include variables within expressions + +## Variable Editor + +The [Variable Editor][] allows the the developer to [create][] and [use][] variables whilst configuring a [block][]. + +### Creating a Variable + +If a variable does not already exist, the [Variable Editor][] can be used to [create][Creating Variables] a new one at the [scope][] of the selected [block][]. + +If the variable name is invalid (does not conform with the [C# identifier naming rules][]) then there will be no option to create a new variable. + +### Using a Variable + +The [Variable Editor][] provides a list of variables that are available at the [scope][] of the selected [block][]. + +Typing any text in the [Variable Editor][] will filter the available variables, showing any variable whose name or scope contains the text. + +The Variable Editor also allows for: + +- [Using Items in Collections][] +- [Using Properties of Data Types][] +- [Using Methods of Data Types][] + +#### Using Items in Collections + +Variables that contain a [Collection][] or [String][] data type can have their respective items or characters accessed using index notation: + +- `[0]` gets the first item +- `[1]` gets the second item +- `["key"]` gets the item with the key `"key"`. + +Ranges can also be used within index notation: + +- `[0..3]` gets three items from the first item (inclusively) (i.e. the first, second, and third item) +- `[^1]` gets the last item +- `[^2]` gets the second to last item +- `[..]` gets all items +- `[..3]` gets three items from the first item (inclusively) (i.e. the first, second, and third item) +- `[3..]` gets all items from the fourth item (inclusively) (i.e. the fourth to the last item) + +In the examples below assume: + +- `($)List` has been set to `[1, 2, 3, 4, 5]` +- `($)Dictionary` of type `Dictionary` has been set to `{"FirstKey": 1, "SecondKey": 2}` +- `($)Structure` has been set to `{"FirstKey": 1, "SecondKey": [1, 2, 3]}` +- `($)String` has been set to `"Some Text"`. + +| Text | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `List[2]` | `3` | The third item in the list is returned | +| `List[0..2]` | `[1, 2]` | The first and second item in the list are returned | +| `List[^2]` | `4` | The second to last item in the list is returned | +| `List[^2..^0]` | `[4, 5]` | The second to last and the last item in the list are returned | +| `List[1..^1]` | `[2, 3, 4]` | The second item to the second to last item in the list are returned | +| `List[..]` | `[1, 2, 3, 4, 5]` | All items in the list are returned | +| `List[..2]` | `[1, 2]` | The first item and the second item in the list are returned | +| `List[2..]` | `[3, 4, 5]` | The third item to the last item in the list are returned | +| `Dictionary["FirstKey"]` | `1` | The item with the key `"FirstKey"` is returned | +| `Structure["SecondKey"]` | `[1, 2, 3]` | The item with the key `"SecondKey"` is returned | +| `Structure["SecondKey"][0]` | `1` | The first item within the item with key `"SecondKey"` is returned | +| `String[0]` | `'S'` | The first character in the string is returned | + +#### Using Properties of Data Types + +[Properties][] can be used to read data from and/or write data to a variable. The properties accessible are defined by the [Data Type][], and information regarding properties can be found in the relevant documentation for that [Data Type][]. + +[Properties][] can be read-write, read-only, or write-only (extremely rare) depending on the access specified by the [Data Type][]. + +Whilst [Structures][Structure] are [Collections][Collection], they also allow for their keys to be accessed as [properties][Properties]. + +In the examples below assume: + +- `($)List` has been set to `[1, 2, 3]` +- `($)TimePeriod` has been set to `{"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}` +- `($)Structure` has been set to `{"FirstKey": 1, "SecondKey": 2}` + +| Text | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `List.Count` | `3` | Read-only property, this only works in [Input Properties][] | +| `TimePeriod.Years` | `1` | Read-write property, this can be used in [Input][Input Properties], [Output][Output Properties], and [InputOutput Properties][]. The result column shows reading the property; writing to the property can be achieved by using any [Output Property][Output Properties]. | +| `Structure.FirstKey` | `1` | Read-write property, this can be used in [Input][Input Properties], [Output][Output Properties], and [InputOutput Properties][]. The result column shows reading the property; writing to the property can be achieved by using any [Output Property][Output Properties]. | + +#### Using Methods of Data Types + +[Methods][] can be used to execute specific functionality. The methods accessible are defined by the [Data Type][], and information regarding methods can be found in the relevant documentation for that [Data Type][]. + +[Methods][] can have parameters passed into them that are then used to execute the functionality, not all methods have parameters. The same method can be defined multiple times, each with different sets of parameters. + +In the examples below assume the variable `($)Int` has been set to `1`. + +| Text | Result | Notes | +|--------------------------------|---------|------------------------------------| +| `Int.ToString()` | `"1"` | Method without parameters | +| `Int.ToString("P0")` | `"100%"` | The `ToString()` method can take parameters in order to format the result. In this case `1` was converted into a percent with zero decimal places | + +## Expression Editor + +Variables are named containers for storing values of any [data type][Data Type]; a variable can be included within [expressions][] created using the [Expression Editor][]. A variable is used by prefixing the variable's name with `($)` (e.g. `($)VariableName`). + +## Remarks + +### Case Sensitivity + +When using variables in the [Variable][Variable Editor] or [Expression Editor][], the names are case insensitive. For example, `List` is the same as `list`. + +When using [properties][Properties] or [methods][Methods] of any variable, or items in [Collections][Collection] (e.g. [Dictionaries][Dictionary], [Structures][Structure] etc.), their names are case sensitive. + +For Example: + +| Text | Notes | +|--------------------------------|------------------------------------| +| `FlowException.Message` | `Message` property cannot be accessed using `FlowException.message` | +| `Int.ToString()` | `ToString()` method cannot be accessed using `Int.toString()` | +| `Dictionary["Item1"]` | `"Item1"` item cannot be accessed using the key `Dictionary["item1"]` | + +### Known Limitations + +#### When using variables of the same name the closest scoped is used + +It is possible to create multiple variables with the same name in the [Variables Grid][]. When using the same name in different [workspaces][workspace], the variable with the closest scope will be used. + +For example: + +- `Top-Level` workspace has the variable `($)Variable` +- `Child-Level` workspace also has the variable `($)Variable` + +When executing a block in `Child-Level` that uses `($)Variable`, the variable that is used is the variable defined in `Child-Level`. + +This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario. + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Block Properties][] + +### Related Data Types + +- [All Data Types][Data Type] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Using Variables: Variable Editor]: {{< ref "#variable-editor" >}} +[Using Variables: Expression Editor]: {{< ref "#expression-editor" >}} +[create]: {{< ref "#creating-a-variable" >}} +[use]: {{< ref "#using-a-variable" >}} + +[Using Items in Collections]: {{< ref "#using-items-in-collections" >}} +[Using Properties of Data Types]: {{< ref "#using-properties-of-data-types" >}} +[Using Methods of Data Types]: {{< ref "#using-methods-of-data-types" >}} + +[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" >}} +[Input Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Property Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.MainDoc" >}} +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.Expressions" >}} +[Creating Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.CreatingVariables" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Set Variable]: {{< url path="Cortex.Reference.Blocks.Variables.SetVariable.SetVariable.MainDoc" >}} + +[Data Type]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} +[Collection]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Variables Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.VariablesGrid" >}} +[Variable Editor]: {{< url path="Cortex.Guides.Studio.VariableEditor.MainDoc" >}} + +[Properties]: {{< url path="Cortex.Reference.Glossary.P-T.PropertyCSharp" >}} +[Methods]: {{< url path="Cortex.Reference.Glossary.K-O.Method" >}} +[programming language]: {{< url path="Cortex.Reference.Glossary.P-T.ProgrammingLanguage" >}} + +[C# identifier naming rules]: {{< url path="MSDocs.CSharp.IdentifierNamingRules" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/variable-scopes.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/variable-scopes.md new file mode 100644 index 000000000..160245078 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/variable-scopes.md @@ -0,0 +1,99 @@ +--- +title: "Variable Scopes" +linkTitle: "Variable Scopes" +description: "Information regarding variable scopes, including: what they are, creating variables at a specific scope, and changing a variable's scope." +weight: 200 +--- +# {{% param title %}} + +## Summary + +Each [workspace][] in a [flow][] has a scope. A scope is where [variables][variable] are defined and controls where they can be used. + +Variables can only be used in the workspace of the scope they are defined in and any descendant workspaces. Only variables in scope will be available in the [Variable Editor][], or the [Expression Editor][] using [snippets][]. For an example see [Accessing Variables from Other Scopes][]. + +When the [flow execution][execution] exits a workspace, any local-scope variables that have been declared in that workspace are deleted and their values, if any, are lost. + +## Accessing Variables from Other Scopes + +For example, the table below shows a hierarchy of workspaces and which variables are available to each workspace due to their scope: + +| Workspace Name | Parent Workspace | Defined Variables | Available Variables | +|----------------|------------------|-------------------|---------------------| +| Top-Level Workspace | N/A |
  • GlobalVarA
  • GlobalVarB
|
  • GlobalVarA
  • GlobalVarB
| +| ChildWorkspace1 | Top-Level Workspace |
  • ChildVarA
  • ChildVarB
|
  • GlobalVarA
  • GlobalVarB
  • ChildVarA
  • ChildVarB
| +| ChildWorkspace2 | Top-Level Workspace |
  • ChildVarC
  • ChildVarD
|
  • GlobalVarA
  • GlobalVarB
  • ChildVarC
  • ChildVarD
| +| GrandChildWorkspace1 | ChildWorkspace1 |
  • GrandChildVarA
  • GrandChildVarB
|
  • GlobalVarA
  • GlobalVarB
  • ChildVarA
  • ChildVarB
  • GrandChildVarA
  • GrandChildVarB
| +| GrandChildWorkspace2 | ChildWorkspace2 |
  • GrandChildVarC
  • GrandChildVarD
|
  • GlobalVarA
  • GlobalVarB
  • ChildVarC
  • ChildVarD
  • GrandChildVarC
  • GrandChildVarD
| + +## Creating Variables at a Specific Scope + +[Variables][variable] can be created by using the [Variables Grid][Grid: Creating Variables], or through the use of the [Variable Editor][Editor: Creating Variables]. When a new variable is created, it is created in the scope of the currently selected [workspace][]. It is possible to [Change a Variable's Scope][Changing a Variable's Scope] + +## Changing a Variable's Scope + +A [variable's][variable] scope can be changed by using the [Variables Grid][Grid: Changing a Variable's Scope]. + +## Remarks + +### Known Limitations + +#### When using variables of the same name the closest scoped is used + +It is possible to create multiple [variables][variable] with the same name in the [Variables Grid][]. When using the same name in different [workspaces][workspace], the variable with the closest scope will be used. + +For example: + +- `Top-Level` workspace has the variable `($)Variable` +- `Child-Level` workspace also has the variable `($)Variable` + +When executing a block in `Child-Level` that uses `($)Variable`, the variable that is used is the variable defined in `Child-Level`. + +This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario. + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Block Properties][] +- [Executions][] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Accessing Variables from Other Scopes]: {{< ref "#accessing-variables-from-other-scopes" >}} +[Changing a Variable's Scope]: {{< ref "#changing-a-variables-scope" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Editor: Creating Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.CreatingVariables" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[Variables Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.VariablesGrid" >}} +[Grid: Creating Variables]: {{< url path="Cortex.Guides.Studio.SouthPanel.CreatingVariables" >}} +[Grid: Changing a Variable's Scope]: {{< url path="Cortex.Guides.Studio.SouthPanel.ChangingAVariablesScope" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[snippets]: {{< url path="Cortex.Reference.Glossary.P-T.Snippets" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/what-is-a-variable.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/what-is-a-variable.md new file mode 100644 index 000000000..fc61ec3f1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/variables/what-is-a-variable.md @@ -0,0 +1,259 @@ +--- +title: "What is a Variable?" +linkTitle: "What is a Variable?" +description: "Information regarding the anatomy of a variable, using variables at design and runtime, and variable typing." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +A variable is a named container for storing data that can then be used in [Block Properties][]. + +Data in a variable can be read, updated, or removed by different blocks. Examples of these include: + +- Add an item to a [List][] +- Remove an item from a [List][] +- Get an item from a [Dictionary][] +- Set an item in a [Dictionary][] + +## Anatomy of a Variable + +{{< figure src="/images/variables-grid.PNG" >}} + +Variables have the following properties that can be configured in the [Variables Grid][]: + +| Variable Property | Notes | +|-------------|-------------| +| Description | Description of the variable's purpose | +| Name | Name of the variable | +| Type | Will default to variable. Read-only, reserved for future use | +| Set Default Value? | Sets the variable to be initialised to the **Default Value** if set to `true`, otherwise **Default Value** is ignored | +| Default Value | The value to initialise the variable to if **Set Default Value?** is set to `true`. See [Variables with a Default Value][] | +| Is Input Variable? | Marks the variable as an input if set to `true`, requiring data to be passed into the variable when the flow is triggered | +| Is Output Variable? | Marks the variable as an output if set to `true`. All output variables will be returned as items in a [Structure][]. See [Output Variables Structure][] | + +### Variables with a Default Value + +Variables can be initialised with a default value. The Default Value can be set to any valid expression or literal, but cannot include any variables. + +For example, the following expression is valid as it does not use any variables: + +```c# +"Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;" +``` + +The following expression is invalid as it uses the `($)ServerName` variable: + +```c# +$@"Server={($)ServerName};Database=myDataBase;User Id=myUsername;Password=myPassword;" +``` + +### Output Variables Structure + +When any variables have their `Is Output Variable?` property set to `true`, they will be returned to the caller as items in a [Structure][] when the flow ends. + +In the following example `($)TotalUnreadEmails` and `($)FoldersWithUnreadEmails` are both set as outputs and the following [Structure][] is returned: + +```json +{ + "TotalUnreadEmails":12, + "FoldersWithUnreadEmails": { + "Inbox": 8, + "Junk": 4 + } +} +``` + +## Variables at Design Time + +The [Variables Grid][] is used to [create][], [view][], [modify][], and [delete][] variables. It is opened by clicking `Variables` tab at the bottom of [{{% ctx %}} Studio][CORTEX Studio]. For more information see [Variables Grid][]. + +Variables can also be created through the use of the [Variable Editor][]. For more information see [Creating Variables][]. + +## Variables at Runtime + +### Initialising Variables + +Variables must be initialised with data before they can be used in a block. + +If an [Input][] or [InputOutput][] property [uses a variable][] that has not been initialised, a [Message][Messages] will be returned stating `Variable is not initialised`, and the name of the variable will be included within the details of the message. The [Message][Messages] will be: + +- Displayed in the [Messages Grid][] when [debugging a flow][] in [{{% ctx %}} Studio][CORTEX Studio] +- Returned as an exception to the caller when a flow is triggered via the [API Gateway Service][] + +Variables can be initialised in the following ways: + +- Using a [Flow Input Variable][] +- Using the [Default Value][] +- Using a [Block Output Property][] + +#### Flow Input Variable + +If a variable has its `Is Input Variable?` property set to `true`, and no [Default Value][] has been set, then a value must be provided for the variable when the flow is triggered. When the execution starts, the variable is initialised with the value provided. + +#### Default Value + +If a variable has its `Set Default Value?` property set to `true`, it will be initialised with the `Default Value` provided when the flow is executed. + +If a variable has its `Is Input Variable?` and `Set Default Value?` properties set to `true`, then it will be initialised with the value provided when the flow is triggered. If no value is provided then it will be initialised with the `Default Value`. + +#### Block Output Property + +[Output Properties][Output] are used to save values to a variable during the execution of a block, regardless of whether the variable is already initialised or not. The act of saving to an uninitialised variable will initialise it. + +### Viewing Variables + +When [debugging a flow][debugging a flow] in [{{% ctx %}} Studio][CORTEX Studio], selecting an execution will display all initialised variables that are in [scope][] in the [Variables Viewer][]. + +{{< figure src="/images/reference/concepts/fundamentals/variables/what-is-a-variable-variable-panel-2.png" >}} + +#### Viewing Basic Data Types + +When a variable contains a [basic data type][] (e.g. String, Integer, etc), the value will be displayed directly in the [Variables Viewer][]. Strings will be surrounded by double quotes (e.g. `"MyString"`). + +#### Viewing Complex Data Types + +When a variable contains a [complex data type][] that is not a collection data type (e.g. Command or FlowException), the value will be displayed as `Instance of Command` or `Instance of FlowException` respectively in the [Variables Viewer][]. + +When a variable contains a [collection data type][Collections] (e.g. Dictionary, List, or Structure), the [Variables Viewer][] will specify the data type and how many items the collection contains (e.g. `Dictionary with 2 item(s)`). + +To see the data in the variable, select the variable in the [Variables Viewer][] and the data will be presented in the [Variable Details Viewer][]. + +The following examples show the [Variable Details Viewer][] when showing a: + +- [Dictionary][Dictionary] variable + +{{< figure src="/images/reference/concepts/fundamentals/variables/what-is-a-variable-dictionary-panel.png" >}} + +- [Command][] variable + +{{< figure src="/images/reference/concepts/fundamentals/variables/what-is-a-variable-command-panel.png" >}} + +- [FlowException][] variable + +{{< figure src="/images/reference/concepts/fundamentals/variables/what-is-a-variable-exception-panel.png" >}} + +### Updating Variables + +[InputOutput][] and [Output][] properties are used to save values and update variables during the execution of a block. + +### Deleting Variables + +When an execution exits a [workspace][], any variables defined within that workspace's [scope][] will be deleted from the execution. This means the variables: + +- Are no longer accessible to the execution +- Are no longer presented in the [Variables Viewer][] when the flow is being debugged + +If the execution re-enters the workspace's [scope][], any variables will be [re-initialised][Initialising Variables]. + +## Variable Typing + +Variables do not have their own [data type][Data Types Concept]; they are named containers for storing data of any [data type][Data Types Concept]. + +When a variable is used in a [Block Property][Block Properties] it is checked to ensure the data type it contains is supported by the property. For all data types apart from [dynamic][] any variables containing unsupported data types will be displayed in the [Messages Grid][], preventing the execution from starting; for variables containing [dynamic][] data types checking will be performed during the block execution, throwing an exception if the data type is unsupported. + +Sometimes an unsupported data type can automatically be converted to a supported type through the use of [implicit casting][implicitly cast]; if this is possible the block property will handle this without any input required by the developer. However, if this is not possible an unsupported data type must be converted to a supported type by the developer; this can be done by: + +- [Explicitly casting][explicitly cast] the unsupported [Data Type][Data Types] +- Converting the unsupported [Data Type][Data Types] through the use of methods and properties (e.g. `Convert.ToInt32(($)String)` or `Int32.Parse(($)String)`) + +For more information on specific data type conversions, see the relevant documentation for that [Data Type][Data Types]. + +## Remarks + +### Known Limitations + +#### Default Value can not use Variables + +Currently, default values cannot use variables. However, this may change in the future. + +For examples of valid and invalid default values see [Variables with a Default Value][]. + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Block Properties][] +- [Data Types][Data Types Concept] +- [Executions][] +- [Exceptions][] +- [Messages][Messages Concept] + +### Related Data Types + +- [All Data Types][Data Types] + +### Related Blocks + +- [All Blocks][] + +### External Documentation + +None + +[Variables with a Default Value]: {{< ref "#variables-with-a-default-value" >}} +[Output Variables Structure]: {{< ref "#output-variables-structure" >}} +[Flow Input Variable]: {{< ref "#flow-input-variable" >}} +[Default Value]: {{< ref "#default-value" >}} +[Block Output Property]: {{< ref "#block-output-property" >}} +[Initialising Variables]: {{< ref "#initialising-variables" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[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" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Creating Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.CreatingVariables" >}} + +[Data Types Concept]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} +[basic data type]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.BasicDataTypes" >}} +[complex data type]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.WhatIsADataType.ComplexDataTypes" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[debugging a flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Messages Concept]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.MainDoc" >}} +[Messages]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Messages.WhatIsAMessage.MainDoc" >}} + +[uses a variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.UsingVariables.MainDoc" >}} +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} + +[implicitly cast]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ImplicitCast" >}} +[explicitly cast]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[API Gateway Service]: {{< url path="Cortex.Reference.Apis.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Collections]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} + +[FlowException]: {{< url path="Cortex.Reference.Exceptions.Flows.FlowException.MainDoc" >}} + +[CORTEX Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Variables Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.VariablesViewer" >}} +[Variable Details Viewer]: {{< url path="Cortex.Guides.Studio.EastPanel.VariableDetailsViewer" >}} +[Messages Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.MessagesGrid" >}} +[Variables Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.VariablesGrid" >}} +[create]: {{< url path="Cortex.Guides.Studio.SouthPanel.CreatingVariables" >}} +[view]: {{< url path="Cortex.Guides.Studio.SouthPanel.ViewingVariables" >}} +[modify]: {{< url path="Cortex.Guides.Studio.SouthPanel.ModifyingVariables" >}} +[delete]: {{< url path="Cortex.Guides.Studio.SouthPanel.DeletingVariables" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/_index.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/_index.md new file mode 100644 index 000000000..f49bf63c2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/_index.md @@ -0,0 +1,6 @@ +--- +title: "Workspaces" +linkTitle: "Workspaces" +description: "Information regarding what a workspace is, workspace scopes, and handling exceptions within a workspace." +weight: 100 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/handling-exceptions-within-a-workspace.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/handling-exceptions-within-a-workspace.md new file mode 100644 index 000000000..178cdbab7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/handling-exceptions-within-a-workspace.md @@ -0,0 +1,64 @@ +--- +title: "Handling Exceptions within a Workspace" +linkTitle: "Handling Exceptions within a Workspace" +description: "Information regarding handling exceptions at different levels within a workspace." +weight: 100 +--- + +# {{% param title %}} + +## Summary + +Exceptions within a workspace can be handled at the following levels: + +- The [block level][] (Highest Priority) +- The [workspace level][] +- The [flow level][] (Lowest Priority) + +A single [Handle Workspace Exception][] block may be placed on a [workspace][] to handle any exceptions that are not handled at the [block level][]. + +For more information, see [Handling Exceptions][]. + +## Remarks + +### Known Limitations + +#### Handle Workspace Exception block can only be used once per execution of a Workspace + +The [Handle Workspace Exception][] block will only handle the first unhandled exception within its workspace. Subsequent unhandled exceptions are passed to the next relevant exception handling block. In future this limitation may be removed. + +## See Also + +### Related Concepts + +- [Flows][] +- [Workspaces][] +- [Blocks][] +- [Executions][] +- [Exceptions][] + +### Related Blocks + +- [Handle Workspace Exception][] + +### External Documentation + +None + +[Handle Workspace Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleWorkspace.HandleWorkspaceException.MainDoc" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Handling Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.MainDoc" >}} +[block level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.BlockLevel" >}} +[flow level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.FlowLevel" >}} +[workspace level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.WorkspaceLevel" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} +[flow execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Workspaces]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.MainDoc" >}} +[workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.WhatIsAWorkspace.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/what-is-a-workspace.md b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/what-is-a-workspace.md new file mode 100644 index 000000000..9cc71a32a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/fundamentals/workspaces/what-is-a-workspace.md @@ -0,0 +1,176 @@ +--- +title: "What is a Workspace?" +linkTitle: "What is a Workspace?" +description: "Information regarding the anatomy of a workspace, nested workspaces, variable scope, and handling exceptions within a workspace." +weight: 1 +--- + +# {{% param title %}} + +## Summary + +A workspace is used to group logic and actions within a [flow][], in order to reduce the complexity and make the flow easier to maintain. + +## Anatomy of a Workspace + +### Top-Level Workspace + +A flow can only contain one Top-Level Workspace, which acts as the entry point for the [flow execution][]. + +{{< figure src="/images/top-level-workspace-activity.svg" title="Example Top-Level Workspace" >}} + +* Start Flow block + * Identifies where the [flow execution][] will start + * Automatically created when the flow is created + * Cannot be deleted + * See [Start Flow][] block +* Action blocks + * Performs a specific action + * Icon on block indicates the nature of the action + * See [Blocks][Reference Blocks] +* Decision block + * Causes the [flow execution][] to branch, dependent on a condition + * Icon on block indicates type of condition causing branching + * See [Decision Blocks][Decision Blocks] +* Workspace blocks + * Contains grouped flow logic + * The turndown on the top-right of the icon indicates it contains a workspace, which can be opened by double-clicking the icon + * See [Workspace][Workspace Block] block +* End Flow block + * Ends the [flow execution][] + * Automatically created when the flow is created + * See [End Flow][] block +* Handle Flow Exception block + * Handles [flow level exceptions][flow level], thrown during the [flow execution][] + * Automatically created when the flow is created + * The turndown on the top-right of the icon indicates it contains a workspace, which can be opened by double-clicking the icon + * Cannot be deleted + * See [Handle Flow Exception][] block +* Flow Variable Store + * This is deprecated in favour of the [Variables Grid][] + * The [Variables Grid][] can be opened by double-clicking the icon, the scope will be set to `Defined (Selected Workspace)` + * Cannot be deleted +* Workspace + * The Top-Level Workspace within the flow + * Canvas on which blocks are placed and connected to create the flow logic + +{{% alert title="Note" %}} +The flow should be ended with an {{< ahref path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" title="End Flow" >}} block, but it can also be ended using an {{< ahref path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" title="End Workspace" >}} block on the [Top-Level Workspace]({{< ref "#top-level-workspace" >}}). +{{% /alert %}} + +### Other Workspaces + +A flow can contain any number of other workspaces that are not the Top-Level Workspace, these act as a means to grouping logic and actions to reduce the complexity and make the flow easier to maintain. + +{{< figure src="/images/nested-workspace.svg" title="Example Workspace" >}} + +* Start Workspace block + * Identifies where the [flow execution][] will start when the workspace is executed + * Automatically created when the workspace is created + * Cannot be deleted + * See [Start Workspace][] block +* Action blocks + * Performs a specific action + * Icon on block indicates the nature of the action + * See [Blocks][Reference Blocks] +* End Workspace block + * Ends the execution of the workspace + * Automatically created when the workspace is created + * See [End Workspace][] block +* End Flow block + * Ends the [flow execution][] + * See [End Flow][] block +* Handle Workspace Exception block + * Handles [workspace level exceptions][], thrown during the [flow execution][] + * See [Handle Workspace Exception][] block +* Workspace Variable Store + * This is deprecated in favour of the [Variables Grid][] + * The [Variables Grid][] can be opened by double-clicking the icon, the scope will be set to `Defined (Selected Workspace)` + * Cannot be deleted +* Workspace + * A nested workspace within the flow + * Canvas on which blocks are placed and connected to create the workspace logic + +## Nested Workspaces + +All the logic of a flow can exist on the [Top-Level Workspace][], however, this can quickly become difficult to maintain and understand as the numbers of blocks increase. Blocks can be grouped into workspaces in order to reduce the complexity and make the flow easier to maintain. + +A [Workspace][Workspace Block] block can opened by double clicking it, showing its workspace canvas and the logic inside; this could include blocks for executing specific functions or other workspaces to help separate the logic of the flow further. + +When an [End Workspace][] block is executed, the [flow execution][] returns to the parent workspace. However, when an [End Flow][] block is executed the [flow execution][] will end. + +A nested workspace has access to any variables defined within its [scope][], or any direct ancestors [scope][]. + +## Exceptions within a Workspace + +Workspaces support hierarchical exception handling at any level within the workspace. + +Exceptions can be handled: + +* At the [block][] level; for further information, see [Handling Exceptions within a Block][] +* At the workspace level; for further information, see [Handling Exceptions within a Workspace][] + +A [Top-Level Workspace][] can also handle exceptions at the [flow][] level; for further information, see [Handling Exceptions within a Flow][] + +## Remarks + +### Known Limitations + +#### Cannot have a Handle Workspace Exception block on the flow's Top-Level Workspace + +Currently, it is not possible to have a [Handle Workspace Exception][] block on the [Top-Level Workspace][] of a flow. In future this limitation may be removed. + +## See Also + +### Related Concepts + +* [Flows][] +* [Blocks][] +* [Executions][] +* [Exceptions][] + +### Related Blocks + +* [Start Flow][] +* [End Flow][] +* [Handle Flow Exception][] +* [Start Workspace][] +* [End Workspace][] +* [Handle Workspace Exception][] +* [Workspace][Workspace Block] + +### External Documentation + +None + +[Top-Level Workspace]: {{< ref "#top-level-workspace" >}} + +[Reference Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Decision Blocks]: {{< url path="Cortex.Reference.Blocks.Decisions.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" >}} +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} +[Workspace Block]: {{< url path="Cortex.Reference.Blocks.Workspaces.Workspace.Workspace.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]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.WhatIsABlock.MainDoc" >}} +[Handling Exceptions within a Block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.HandlingExceptionsWithinABlock.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[workspace level exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.WorkspaceLevel" >}} + +[Executions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.MainDoc" >}} + +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" >}} +[Handling Exceptions within a Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.HandlingExceptionsWithinAFlow.MainDoc" >}} +[flow execution]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution.MainDoc" >}} +[flow level]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.HandlingExceptions.FlowLevel" >}} + +[scope]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.VariableScopes.MainDoc" >}} +[Handling Exceptions within a Workspace]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Workspaces.HandlingExceptionsWithinAWorkspace.MainDoc" >}} + +[Variables Grid]: {{< url path="Cortex.Guides.Studio.SouthPanel.VariablesGrid" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/_index.md new file mode 100644 index 000000000..4a1c3132c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/_index.md @@ -0,0 +1,8 @@ +--- +title: "Working With..." +linkTitle: "Working With..." +description: "This section includes all reference documentation for concepts required to use {{% ctx %}} Innovation." +weight: 2 +--- + + diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/_index.md new file mode 100644 index 000000000..3a5989e7f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/_index.md @@ -0,0 +1,5 @@ +--- +title: "Collections" +linkTitle: "Collections" +description: "Information related to working with collections such as Lists, Dictionaries and Structures." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/indexes.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/indexes.md new file mode 100644 index 000000000..f8f540589 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/indexes.md @@ -0,0 +1,50 @@ +--- +title: "Indexes" +linkTitle: "Indexes" +description: "Information related to working with Indexes." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Overview/summary +- What is an Index? +- How are they accessed? +- Indexes are zero based +- Difference between occurrence and indexes + +## Accessing an item using Indexes + +[Indexes][] can be used in the [Expression Editor][] to access items in a Collection. + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Indexes]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.IndexExpressions" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/items.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/items.md new file mode 100644 index 000000000..816bde126 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/items.md @@ -0,0 +1,46 @@ +--- +title: "Items" +linkTitle: "Items" +description: "Information related to working with Items." +weight: 100 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Overview/summary +- What is an Item? +- How are they accessed? + - Link to Indexes + - Link to Keys +- If you are using C# syntax, then the equality is done using reference equality for reference types, and value equality for value types +- If you are using List of Dictionary blocks, then the equality is done using reference equality for reference types and falls back to value equality if no reference was found, and value equality for value types + +## Remarks + +### Known Limitations + +None + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/keys.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/keys.md new file mode 100644 index 000000000..7361f5a06 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/keys.md @@ -0,0 +1,57 @@ +--- +title: "Keys" +linkTitle: "Keys" +description: "Information related to working with Keys." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Overview/summary +- What is a Key? +- How are they accessed? +- The type of the Key depends on the data type +- Keys are unique +- Keys cannot be null +- If you are using C# syntax, then the equality is done using reference equality for reference types, and value equality for value types +- If you are using Dictionary blocks, then the equality is done using reference equality for reference types and falls back to value equality if no reference was found, and value equality for value types + +## Accessing an item using Keys + +[Keys][] can be used in the [Expression Editor][] to access items in a Collection. + +## Remarks + +### Known Limitations + +#### Complex Keys do not show sho correctly in the Variable Details Viewer + +Currently, if a Dictionary is shown in the Variable Details Viewer and contains Complex Data types as its keys, the data within the variable will not be displayed correctly. + +In the future this limitation may be removed. + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + +[Expression Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Keys]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.IndexExpressions" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/occurrences.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/occurrences.md new file mode 100644 index 000000000..ceec95a19 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/occurrences.md @@ -0,0 +1,66 @@ +--- +title: "Occurrences" +linkTitle: "Occurrences" +description: "Information related to working with Occurrences." +--- + +# {{% param title %}} + +## Summary + +TODO + +- Summary +- What is an Occurrence? +- How are they accessed? + - Positive or Negative int properties on blocks that operate on single items +- Difference between occurrence and indexes +- specified occurrence + +## Positive Occurrences + +TODO: + +- Get First, Second, Third, Nth + +## Negative Occurrences + +TODO: + +- Get Last, Second from Last, Third from Last, Nth from Last + +## Remarks + +### Occurrence Not Present + +TODO: + +Blocks will either throw an exception if the occurrence is not present (e.g. OccurrenceNotPresentException), or they will handle the occurrence not being present either by performing no operation or by returning a predetermined value. + +For example: + +- Get Index Of Item With Value (returns predetermined value) +- Remove Item With Value (no operation performed) +- Get Item With Key (throws OccurrenceNotPresentException) + +### Known Limitations + +None + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/collections/what-is-a-collection.md b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/what-is-a-collection.md new file mode 100644 index 000000000..99be3b3b1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/collections/what-is-a-collection.md @@ -0,0 +1,125 @@ +--- +title: "What is a Collection?" +linkTitle: "What is a Collection?" +description: "Information regarding what a collection is, and the different types of collections." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Types of Collections + +### Dictionaries + +TODO: + +- Talk about typed dictionaries (TKey, TItem) +- Talk about heterogenous vs homogenous dictionaries (fix single data type vs multiple data types links in all dictionary blocks) +- Talk about keys, uniqueness and equality (link to Keys page) +- Talk about complex keys (link to Keys page) +- Items can be accessed as indexes +- Link to Data Type +- Creating a Dictionary + +#### Accessing Items + +##### Keys + +### Structures + +TODO: + +- Structures are IDictionary<string, object> underlying (how does this interact with blocks?) + - Talk about {} and dynamic vs object +- Talk about keys, uniqueness and equality (link to Keys page) +- Items can be accessed as indexes or properties +- Link to Data Type +- Creating a Structure + +#### Accessing Items + +##### Properties + +##### Keys + +### Lists + +TODO: + +- Talk about typed dictionaries (TItem) +- Talk about [] and dynamic vs object +- Talk about typed lists +- Talk about heterogenous vs homogenous lists (fix single data type vs multiple data types links in all list blocks) +- Items can be accessed as indexes +- Link to Data Type +- Creating a List + +#### Accessing Items + +##### Indexes + +### Queues + +TODO: + +- Talk about first-in-first-out +- Talk about priority and order items in a queue +- Talk about typed queues +- Talk about how items can be accessed (e.g. dequeue/peek or get list of items) +- Link to Data Type +- Creating a queue + +### Data Storage Collection + +TODO: + +- Talk about persistence +- Talk about about heterogenous property (takes any data type and can not be restricted) +- Talk about keys and uniqueness of keys (link to keys page) +- Items can only be accessed via key +- Mention high availability? +- Mention api access? + +## Arrays vs Lists + +### Differences + +### When To Use Arrays + +### When To Use Lists + +- TODO: Some info on when to use array vs list - https://www.educba.com/c-sharp-list-vs-array/ + +## Remarks + +### Known Limitations + +#### Complex Keys do not show sho correctly in the Variable Details Viewer + +Currently, if a Dictionary is shown in the Variable Details Viewer and contains Complex Data types as its keys, the data within the variable will not be displayed correctly. + +In the future this limitation may be removed. + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/_index.md new file mode 100644 index 000000000..32e0a1b80 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/_index.md @@ -0,0 +1,5 @@ +--- +title: "Concurrency" +linkTitle: "Concurrency" +description: "Information related to working with concurrency methods such as Semaphores." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/_index.md new file mode 100644 index 000000000..c28a10b61 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/_index.md @@ -0,0 +1,5 @@ +--- +title: "Semaphores" +linkTitle: "Semaphores" +description: "Information related to working with Semaphores." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/what-is-a-semaphore.md b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/what-is-a-semaphore.md new file mode 100644 index 000000000..872e904ab --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/concurrency/semaphores/what-is-a-semaphore.md @@ -0,0 +1,125 @@ +--- +title: "What is a Semaphore?" +linkTitle: "What is a Semaphore?" +description: "Information regarding what a semaphore is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +A semaphore is a mechanism that limits the number of concurrent executions that can be executing a block or workspace, and can be enabled using the [semaphore property][SemaphoreProperty]. + +The [semaphore property][SemaphoreProperty] is an [advanced property][AdvancedProperties] added to most blocks to allow any part of a flow to be concurrency limited. The [semaphore property][SemaphoreProperty] has a [Scope][] that defines the area in which the semaphore will operate, a [Name][] to identify the semaphore, a [ConcurrencyLimit][] that defines the maximum number of concurrent executions that can enter the semaphore at once and a [Queue][] property that defines whether the execution should [queue][queuing semaphore] or [not queue][non-queuing semaphore] for the semaphore. + +## Anatomy of a Semaphore + +TODO + +### Non-Queuing Semaphore + +A [Non-Queuing Semaphore][] refers to a semaphore where executions do not queue when attempting to acquire a semaphore that has reached its concurrency limit. Instead, it throws a [SemaphoreCouldNotBeAcquiredException][ConcurrencyLimitReached] with the [Queued][] property set to `false` to indicate that it did not queue. + +### Queuing Semaphore + +A [Queuing Semaphore][] refers to a semaphore where executions queue when attempting to acquire a semaphore that has reached its concurrency limit. It will join the queue with the [Priority][] specified in the [Queue][] property and wait to enter the semaphore. When it has reached the front of the queue and there is space inside, it will be removed from the queue and enter the semaphore. The queue orders items by priority, preserving first-in-first-out behaviour between items with the same priority. The item with the lowest priority will be dequeued first. + +If an execution spends more time in the queue than the [QueueTimeout][] specified in the [Queue][] property, it will exit the queue and throw a [SemaphoreCouldNotBeAcquiredException][QueueTimeoutReached] with the [Queued][] property set to `true` to indicate that it attempted to queue. + +## Remarks + +### Automatic Management + +The semaphores are managed automatically, without the need to define and manage the semaphores separately. When a block attempts to acquire a semaphore that does not exist, the semaphore will automatically be created and configured with the defined [ConcurrencyLimit][]. When the last execution in a semaphore is released (last execution exits the semaphore or is stopped from executing while inside), the semaphore is automatically deleted. + +### Multiple Concurrency Limits + +If a block tries to use a semaphore that already exists (using the same [Scope][] and same [Name][]) but specifies a different [ConcurrencyLimit][], the semaphore will continue respecting the [ConcurrencyLimit][] of when it was created. The block will respect the [ConcurrencyLimit][] already set until the semaphore is emptied and is automatically deleted. The semaphore is then able to be recreated with the new [ConcurrencyLimit][]. + +### Preventing Deadlocks + +Deadlocks in flows can occur when multiple executions have acquired different semaphores, and then each execution wants to acquire another semaphore that is being used by another execution, which in turn is waiting for first execution to release its semaphore. E.g. + +``` +There exists two semaphores: + - Semaphore A with a ConcurrencyLimit of 1 and a queue + - Semaphore B with a ConcurrencyLimit of 1 and a queue + +There exists two executions: + - Execution A acquires Semaphore A + - Execution B acquires Semaphore B + - Execution A tries to acquire Semaphore B and joins the queue + - Execution B tries to acquire Semaphore A and joins the queue + + Both Execution A and Execution B are deadlocked. +``` + +In this example, Execution A can't proceed as it's waiting for the semaphore that Execution B is using; which in turn is waiting for the semaphore that Execution A is using. + +The best way to avoid these deadlocks is to design your flows to avoid them happening in the first place. In the example above, if both executions will need both semaphores to operate, a change that could be made would be to combine both semaphores into one. + +Another way to mitigate the problem would be to use the [QueueTimeout][] property when defining the [QueueSettings][] for each semaphore. Setting the [QueueTimeout][] to a duration reasonably higher than the expected execution time of the operations inside of the semaphore would allow the execution to throw if it has been waiting too long, likely due to a deadlock having occurred. The [SemaphoreCouldNotBeAcquiredException][QueueTimeoutReached] thrown could then be caught to allow the execution to release its semaphores and try again. In the example above, if Semaphore A had a [QueueTimeout][], Execution B timeouts out as it waits to acquire Semaphore A and releases Semaphore B. Execution A then acquires Semaphore B. Execution B retries to acquire Semaphore B and joins the queue. Execution A then finishes its operations, releasing both semaphores and allows Execution B to complete its operations as well. + +### Known Limitations + +None + +## See Also + +### Related Concepts + +None + +### Related Data Types + +- [QueueSettings][] +- [ScopeDefinition][ScopeDatatype] +- [SemaphoreSettings][] + +### Related Blocks + +- [All Blocks][] + +Except: + +- [End Flow][] +- [End Workspace][] +- [Handle Flow Exception][] +- [Start Flow][] +- [Wait For Duration][] + +### External Documentation + +None + +[Queuing Semaphore]: {{< ref "#queuing-semaphore" >}} +[Non-Queuing Semaphore]: {{< ref "#non-queuing-semaphore" >}} + +[ConcurrencyLimitReached]: {{< url path="Cortex.Reference.Exceptions.Concurrency.Semaphores.SemaphoreCouldNotBeAcquiredException.ConcurrencyLimitReached" >}} +[QueueTimeoutReached]: {{< url path="Cortex.Reference.Exceptions.Concurrency.Semaphores.SemaphoreCouldNotBeAcquiredException.QueueTimeoutReached" >}} +[Queued]: {{< url path="Cortex.Reference.Exceptions.Concurrency.Semaphores.SemaphoreCouldNotBeAcquiredException.Queued" >}} + +[SemaphoreProperty]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.SemaphoreProperty" >}} +[AdvancedProperties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[SemaphoreSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.MainDoc" >}} +[QueueSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.MainDoc" >}} +[Priority]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.Priority" >}} +[QueueTimeout]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.QueueTimeout" >}} + +[Scope]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Scope" >}} +[Name]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Name" >}} +[ConcurrencyLimit]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.ConcurrencyLimit" >}} +[Queue]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Queue" >}} + +[ScopeDatatype]: {{< url path = "Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/_index.md new file mode 100644 index 000000000..d2fe28bda --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/_index.md @@ -0,0 +1,5 @@ +--- +title: "Culture" +linkTitle: "Culture" +description: "Information related to working with Culture." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/current-culture.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/current-culture.md new file mode 100644 index 000000000..fe690e697 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/current-culture.md @@ -0,0 +1,38 @@ +--- +title: "Current Culture" +linkTitle: "Current Culture" +description: "Information related to working with Current Culture." +weight: 200 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: summary + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/custom-cultures.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/custom-cultures.md new file mode 100644 index 000000000..a15883e92 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/custom-cultures.md @@ -0,0 +1,38 @@ +--- +title: "Custom Cultures" +linkTitle: "Custom Cultures" +description: "Information related to working with custom cultures." +weight: 400 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: summary + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/invariant-culture.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/invariant-culture.md new file mode 100644 index 000000000..2883b3106 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/invariant-culture.md @@ -0,0 +1,38 @@ +--- +title: "Invariant Culture" +linkTitle: "Invariant Culture" +description: "Information related to working with Invariant Culture." +weight: 100 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: summary + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/specific-cultures.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/specific-cultures.md new file mode 100644 index 000000000..65bd9cb78 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/specific-cultures.md @@ -0,0 +1,40 @@ +--- +title: "Specific Cultures" +linkTitle: "Specific Cultures" +description: "Information related to working with specific cultures." +weight: 300 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: summary + +- For a list of cultures that can be returned on Windows systems see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c under The Language table (`Language tag` defines the code required to create the culture) + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/culture/what-is-a-culture.md b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/what-is-a-culture.md new file mode 100644 index 000000000..17a460f40 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/culture/what-is-a-culture.md @@ -0,0 +1,45 @@ +--- +title: "What is a Culture?" +linkTitle: "What is a Culture?" +description: "Information regarding what a culture is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Types of Culture + +TODO: + +- Link to Culture Pages (Invariant/Current/Specific/Custom) +- For a list of predefined cultures that can be returned on Windows systems see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO: Also need sections in working with text (casing, comparisons/equality, O/S settings), dates and time (formats, O/S settings), numbers (formats, O/S settings) etc specifically for how culture affects things - we can then cross link from here + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/_index.md new file mode 100644 index 000000000..388551e37 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/_index.md @@ -0,0 +1,5 @@ +--- +title: "Data Sources" +linkTitle: "Data Sources" +description: "Information related to working with Data Sources." +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/_index.md new file mode 100644 index 000000000..4184695d9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/_index.md @@ -0,0 +1,5 @@ +--- +title: "Supported Data Sources" +linkTitle: "Supported Data Sources" +description: "Information regarding supported data sources." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/odbc.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/odbc.md new file mode 100644 index 000000000..e22bafadb --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/odbc.md @@ -0,0 +1,40 @@ +--- +title: "ODBC" +linkTitle: "ODBC" +description: "Information regarding ODBC as a data source." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Summary +- Table or other format to display verified data sources (e.g. postgres, mysql, access, excel, oracle) and examples (link to connection strings) + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/oracle.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/oracle.md new file mode 100644 index 000000000..3d0f2d832 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/oracle.md @@ -0,0 +1,40 @@ +--- +title: "Oracle" +linkTitle: "Oracle" +description: "Information regarding Oracle as a data source." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Summary +- Table or other format to display verified data sources (e.g. postgres, mysql, access, excel, oracle) and examples (link to connection strings) + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/sql-server.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/sql-server.md new file mode 100644 index 000000000..2f06517a2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/supported-data-sources/sql-server.md @@ -0,0 +1,45 @@ +--- +title: "SQL Server" +linkTitle: "SQL Server" +description: "Information regarding SQL Server as a data source." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Summary +- Table or other format to display verified data sources (SQL Server versions) and examples (link to connection strings) + +## Remarks + +TODO: + +- Connected as the user running the service or as a custom user (e.g. trusted user vs username and password) + - check that impersonation works with trusted when implemented + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/what-is-a-data-source.md b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/what-is-a-data-source.md new file mode 100644 index 000000000..9cc1efc2d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/data-sources/what-is-a-data-source.md @@ -0,0 +1,53 @@ +--- +title: "What is a Data Source?" +linkTitle: "What is a Data Source?" +description: "Information regarding what a data source is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Supported Data Sources + +TODO: See Supported Data Sources + +## Managing Connections to a Data Source + +TODO: + +- Connections are managed by the block +- See Working with Connections (connection life cycle, using a variable for connections over literal/expression) + +## Remarks + +### Known Limitations + +#### Limited Set of Supported Data Sources + +Currently, there are a limited set of Supported Data Sources. + +In the future this limitation may be removed. + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/_index.md new file mode 100644 index 000000000..a0bff010b --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/_index.md @@ -0,0 +1,5 @@ +--- +title: "Date and Time" +linkTitle: "Date and Time" +description: "Information related to working with Date and Time." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/date-and-time-formatting.md b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/date-and-time-formatting.md new file mode 100644 index 000000000..2edcfc4d4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/date-and-time-formatting.md @@ -0,0 +1,181 @@ +--- +title: "Date and Time Formatting" +linkTitle: "Date and Time Formatting" +description: "This page describes the concept of Date and Time Formatting, including Format Providers, Format Templates and Format Specifiers." +--- + +# {{% param title %}} + +## Overview + +TODO: + +* Overview/summary +* Common formats ISO8601, Invariant Culture + +## Format providers + +TODO: + +* what are they +* ways of creating + * CultureInfo.InvariantCulture + * CultureInfo.CurrentCulture + * new CultureInfo("") + * new CultureInfo("en-GB") + +or + +https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#datetimeformatinfo-properties + +https://learn.microsoft.com/en-us/dotnet/api/system.globalization.datetimeformatinfo?view=net-5.0 + +### Invariant Culture + +TODO: + +* default format `"MM/dd/yyyy HH:mm:ss zzz"` +* rules https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.parse?view=net-5.0 + +### Current Culture + +TODO + +## Format Templates + +Format templates use characters called [format specifiers][] to define the text representation of [DateTimeOffset][] and [DateTime][] values. + +There are two types of format template: + +* [Standard Format Templates][] - use a single character [format specifier][format specifiers] +* [Custom Format Templates][] - use multiple character [format specifiers][] + +Both can be used to define how [DateTimeOffset][] and [DateTime][] values are converted to and from their text representation. + +TODO: + +* *How do they relate to format providers + +### Standard Format Templates + +A standard format template uses a single character [format specifier][format specifiers] to define the text representation of [DateTimeOffset][] and [DateTime][] values and can be used to define how [DateTimeOffset][] and [DateTime][] values are converted to and from their text representation. + +The following table shows all of the standard format templates. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Pattern | Format Specifier | DateTimeOffset Example | DateTime Example | Notes | +|-|-|-|-|-| +| Short Date Pattern | `d` | `2022-07-01T14:00:00.0000000+01:00` -> `1/7/2022` | TODO | See [short date ("d") format specifier] for further information | +| Short Time Pattern | `t` | `2022-07-01T14:00:00.0000000+01:00` -> `2:00 PM` | TODO | See [short time ("t") format specifier] for further information | +| Long Date Pattern | `D` | `2022-07-01T14:00:00.0000000+01:00` -> `5 April 2022` | TODO | See [long date ("D") format specifier] for further information | +| Long Time Pattern | `T` | `2022-07-01T14:00:00.0000000+01:00` -> `2:00:00 PM` | TODO | See [long time ("T") format specifier] for further information | +| Full Date/Time Pattern (Short Time) | `f` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [full date short time ("f") format specifier] for further information | +| Full Date/Time Pattern (Long Time) | `F` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [full date long time ("F") format specifier] for further information | +| General Date/Time Pattern (Short Time) | `g` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [general date short time ("g") format specifier] for further information | +| General Date/Time Pattern (Long Time) | `G` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [general date long time ("G") format specifier] for further information | +| Round-Trip Date/Time Pattern | `O`, `o` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [round-trip ("O", "o") format specifier] for further information | +| RFC1123 Pattern | `R`, `r` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [RFC1123 ("R", "r") format specifier] for further information | +| Sortable Date/Time Pattern | `s` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [sortable ("s") format specifier] for further information | +| Universal Sortable Date/Time Pattern | `u` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [universal sortable ("u") format specifier] for further information | +| Universal Full Date/Time Pattern | `U` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [universal full ("U") format specifier] for further information | +| Month Day Pattern | `M`, `m` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [month ("M", "m") format specifier] for further information | +| Year Month Pattern | `Y`, `y` | `2022-07-01T14:00:00.0000000+01:00` -> `TODO` | TODO | See [year month ("Y") format specifier] for further information | +| Unknown Pattern | Any other single character | N/A | N/A | Throws a [FormatException][] | + +#### Invariant Format Templates + +TODO: + +* Invariant format templates - + * In some cases, the standard format string serves as a convenient abbreviation for a longer custom format string that is invariant. Four standard format strings fall into this category: "O" (or "o"), "R" (or "r"), "s", and "u". These strings correspond to custom format strings defined by the invariant culture. They produce string representations of date and time values that are intended to be identical across cultures. The following table provides information on these four standard date and time format strings. + * TABLE 2 + * Standard format string Defined by DateTimeFormatInfo.InvariantInfo property Custom format string + * "O" or "o" None yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK + * "R" or "r" RFC1123Pattern ddd, dd MMM yyyy HH':'mm':'ss 'GMT' + * "s" SortableDateTimePattern yyyy'-'MM'-'dd'T'HH':'mm':'ss + * "u" UniversalSortableDateTimePattern yyyy'-'MM'-'dd HH':'mm':'ss'Z' + * https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings + +#### ISO 8601 Standard + +TODO: + +* round-trip "O", "o" and sortable "s" complies with ISO +* `yyyy-MM-ddTHH:mm:ss.fffffffK` for `DateTime` +* `yyyy-MM-ddTHH:mm:ss.fffffffzzz` for `DateTimeOffset` + +### Custom Format Templates + +TODO: + +* What are they - multiple character format specifiers +* Some examples +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings + +## Format specifiers + +TODO: + +* what are they +* Table of them +* Some of the commonly used format specifiers are: + * dd: The day of the month, from 01 through 31 + * MM: The month, from 01 through 12 + * yyyy: The year as a four-digit number + * HH: The hour, using a 24-hour clock from 00 to 23 + * hh: The hour, using a 12-hour clock from 01 to 12 + * mm: The minute, from 00 through 59 + * ss: The second, from 00 through 59 + * fff: The number of milliseconds + * tttt: The AM/PM designator + * The full set of allowed format specifiers are as per standard Microsoft .NET Custom Date and Time Format Strings. + +## Operating System Settings + +TODO: + +* How can these affect datetime formats etc. +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#control-panel-settings + +[Standard Format Templates]: {{< ref "#standard-format-templates" >}} +[Custom Format Templates]: {{< ref "#custom-format-templates" >}} +[Format Specifiers]: {{< ref "#format-specifiers" >}} +[Operating System Settings]: {{< ref "#operating-system-settings" >}} + +[Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.MainDoc" >}} + +[short date ("d") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.ShortDateFormat" >}} +[short time ("t") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.ShortTimeFormat" >}} +[long date ("D") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.LongDateFormat" >}} +[long time ("T") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.LongTimeFormat" >}} +[full date short time ("f") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.FullDateShortTimeFormat" >}} +[full date long time ("F") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.FullDateLongTimeFormat" >}} +[general date short time ("g") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.GeneralDateShortTimeFormat" >}} +[general date long time ("G") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.GeneralDateLongTimeFormat" >}} +[round-trip ("O", "o") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.RoundTripFormat" >}} +[RFC1123 ("R", "r") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.RFC1123Format" >}} +[sortable ("s") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.SortableFormat" >}} +[universal sortable ("u") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.UniversalSortableFormat" >}} +[universal full ("U") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.UniversalFullFormat" >}} +[month ("M", "m") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.MonthDayFormat" >}} +[year month ("Y") format specifier]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.YearMonthFormat" >}} + +[FormatException]: {{< url path="MSDocs.DotNet.Api.System.FormatException" >}} + +[DateTime]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTime.MainDoc" >}} +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} + +TODO Add concepts page for string/object formatting that links to: + +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/best-practices-display-data + +TODO Add concepts page for formatting numbers that links to: + +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings +* https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings + +TODO: https://learn.microsoft.com/en-us/dotnet/standard/base-types/parsing-datetime + +TODO: Update examples for most common en-gb os formats diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/what-is-date-and-time.md b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/what-is-date-and-time.md new file mode 100644 index 000000000..01d8fae95 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/date-and-time/what-is-date-and-time.md @@ -0,0 +1,51 @@ +--- +title: "What is Date and Time?" +linkTitle: "What is Date and Time?" +description: "Information regarding what Date and Time is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Date and Time are represented by different data types + - DateTime + - DateTimeOffset + - TimeSpan + - TimePeriod +- What is the difference between DateTime and DateTimeOffset? + - When should they be used +- What is the difference between TimeSpan and TimePeriod? + - When should they be used +- We don't deal with timezone issues within the blocks +- Offsets are handled within DateTimeOffset and can be dealt with using our blocks +- Useful link - https://learn.microsoft.com/en-us/dotnet/api/system.datetime?view=net-6.0 + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/email/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/email/_index.md new file mode 100644 index 000000000..50e6b336a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/email/_index.md @@ -0,0 +1,5 @@ +--- +title: "Email" +linkTitle: "Email" +description: "Information related to working with email." +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/email/authentication.md b/content/en/docs/2024.9/Reference/Concepts/working-with/email/authentication.md new file mode 100644 index 000000000..ec6522f86 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/email/authentication.md @@ -0,0 +1,20 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Information regarding authentication when working with email" +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Overview + +### Setting up an app password for a Gmail account + +### Setting up a Gmail account for OAuth authentication + +### Setting up an Outlook account for OAuth authentication using client credentials + +### Setting up an Outlook account for OAuth authentication using certificate credentials diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/email/what-is-email.md b/content/en/docs/2024.9/Reference/Concepts/working-with/email/what-is-email.md new file mode 100644 index 000000000..cc8fedaaf --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/email/what-is-email.md @@ -0,0 +1,68 @@ +--- +title: "What is Email?" +linkTitle: "What is Email?" +description: "Information regarding what email is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- SMTP (Sending) + - Attachments (best practices): + - where should attachments be in relation to the server the flow is executing on + - should we link to the file path stuff (working with files and folders)? +- IMAP (Retreiving) + - Mailboxes + - Folders: + - Deleted? + - Emails: + - Attachments + - Status: + - Read + - Unread + - Priority + - Body Format + - Flagged +- SSL/TLS +- Authentication: + - Unauthenticated Servers + - SASL + - SMTP Server + - Gmail? + - OAuth: + - Gmail OAuth + - Microsoft365 OAuth + +## Managing Connections to a Mail Server + +TODO: + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/enums/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/enums/_index.md new file mode 100644 index 000000000..21b0ab55f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/enums/_index.md @@ -0,0 +1,5 @@ +--- +title: "Enums" +linkTitle: "Enums" +description: "Information related to working with enum data types such as DayOfWeek, DateTimeComponentType and SearchOptions." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/enums/what-is-an-enum.md b/content/en/docs/2024.9/Reference/Concepts/working-with/enums/what-is-an-enum.md new file mode 100644 index 000000000..e81332ae9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/enums/what-is-an-enum.md @@ -0,0 +1,60 @@ +--- +title: "What is an Enum?" +linkTitle: "What is an Enum?" +description: "Information regarding what an Enum is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Anatomy of an Enum +- Enum literal editor +- Display in studio variable details viewer + - Default + - Overridden types + - Out of range ints cast (DayOfWeek)1000 +- Casting - dayofweek<->Int and unable to cast string - use parse + - Need to cast int to enum or enum to int if comparing +- Enum Types + - DateTimeComponentType + - SearchOptions + - Etc. +- Flagged enums + - Currently not possible to have combined values in the literal editor (is possible in expression) +- Enums names are not localised - e.g. DayOfWeek.Sunday cannot display Dimanche for french +- Links to microsoft docs + - https://learn.microsoft.com/en-us/dotnet/api/system.enum + - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/enum + - probably not: + - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/enums + - https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/enum + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/_index.md new file mode 100644 index 000000000..b315cfd49 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/_index.md @@ -0,0 +1,5 @@ +--- +title: "Files and Folders" +linkTitle: "Files and Folders" +description: "Information related to working with Files and Folders." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/attributes.md b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/attributes.md new file mode 100644 index 000000000..47b4415a0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/attributes.md @@ -0,0 +1,41 @@ +--- +title: "Attributes" +linkTitle: "Attributes" +description: "Information regarding file and folder attributes." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Supported file and folder attributes and examples of using them +- https://learn.microsoft.com/en-us/dotnet/api/system.io.fileattributes?view=net-5.0 +- Currently there are no specific blocks for setting attributes of files and folders (setting can be done through c# or PowerShell) + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/paths.md b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/paths.md new file mode 100644 index 000000000..72b26c7bc --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/paths.md @@ -0,0 +1,53 @@ +--- +title: "Paths" +linkTitle: "Paths" +description: "Information regarding file and folder paths." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Supported file and folder path formats and examples of using them +- How we determine is a path is a folder or a file + - path\ = folder (path with terminating \ or /) + - path = folder (path not ending in extension) + - path.extension = file (path ending in extension) + - path.anotherpartofpath\ = folder (as it ends in a \ or /) +- Valid file and folder names + +Links: + +- https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats +- https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file +- https://learn.microsoft.com/en-us/windows/wsl/filesystems +- https://learn.microsoft.com/en-us/dotnet/standard/io/ +- https://learn.microsoft.com/en-us/dotnet/api/system.io.file?view=net-5.0 + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/what-are-files-and-folders.md b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/what-are-files-and-folders.md new file mode 100644 index 000000000..529943f59 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/files-and-folders/what-are-files-and-folders.md @@ -0,0 +1,46 @@ +--- +title: "What are Files and Folders?" +linkTitle: "What are Files and Folders?" +description: "Information regarding what files and folders are." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- https://learn.microsoft.com/en-us/dotnet/standard/io/ +- https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats +- https://learn.microsoft.com/en-us/dotnet/standard/io/handling-io-errors +- https://learn.microsoft.com/en-us/dotnet/standard/io/common-i-o-tasks +- list of common extensions +- list of common environment variables (`%PROGRAMDATA%` check this works) +- Best Practices (how to work with files, where to save them when working with files and folders in a flow) + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/loops/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/loops/_index.md new file mode 100644 index 000000000..d70e9e9c4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/loops/_index.md @@ -0,0 +1,5 @@ +--- +title: "Loops" +linkTitle: "Loops" +description: "Information related to working with loops, such as for and for each." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/loops/what-is-a-loop.md b/content/en/docs/2024.9/Reference/Concepts/working-with/loops/what-is-a-loop.md new file mode 100644 index 000000000..5cbe0aec5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/loops/what-is-a-loop.md @@ -0,0 +1,74 @@ +--- +title: "What is a Loop?" +linkTitle: "What is a Loop?" +description: "Information regarding what a loop is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Introduce concept of loop + - Why are they used +- Types of Loops (pros and cons) + - For loop + - Can move forwards or backwards + - Can move by single or multiple increments + - Can modify a collection while iterating over it + - Have to manually manage the bounds of the loop + - Index can be adjusted to break a loop + - Decision blocks can be used to break a loop + - For each + - Cannot modify the collection during a for each loop (use a for loop if the collection needs to be modified during the loop) + - Decision blocks can be used to break a loop + - While + - No blocks, can be done using decision blocks looping back into the flow (order of decision block determines while or do while loop) + - Condition can be adjusted to break a loop early + - Decision blocks can be used to break a loop early + - Do while + - No blocks, can be done using decision blocks looping back into the flow (order of decision block determines while or do while loop) + - Condition can be adjusted to break a loop early + - Decision blocks can be used to break a loop early +- Nested loops + - Why they are used + - How nested loops affect performance +- Infinite loops + - Why they are bad, how to avoid + - for loop block protects against infinite loops + - for each loop block cannot have infinite loops as the collection cannot be modified + - while/ do while does not have any protection against infinite loops (must be managed within the flow) + +Links: + +- [Overview: the four different loops of the C# programming language][What is a loop] + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + +[What is a loop]: {{< url path="Kodify.WhatIsALoop" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/_index.md new file mode 100644 index 000000000..8626ac69a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/_index.md @@ -0,0 +1,5 @@ +--- +title: "Numbers" +linkTitle: "Numbers" +description: "Information related to working with Numbers." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/what-is-a-number.md b/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/what-is-a-number.md new file mode 100644 index 000000000..606454bad --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/numbers/what-is-a-number.md @@ -0,0 +1,68 @@ +--- +title: "What is a Number?" +linkTitle: "What is a Number?" +description: "Information regarding what a number is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What is a number +- Types of numbers + - Integer Types + - int, long, etc + - unsigned numbers + - suffixes + - Floating Point Types + - float, double, decimal + - suffixes +- Operators and Comparisons + - Order of operation + - Integer division will result in an integer, not a Floating Point number (e.g. `3 / 2` results in `1`) + - Underflow/Overflow conditions +- Converting numbers to text + - using blocks + - ToString() + - https://learn.microsoft.com/en-us/dotnet/standard/base-types/parsing-numeric +- Converting Integer Types to Floating Types (and reverse) + - Built in numeric conversion - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/numeric-conversions + - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/conversions#1023-implicit-numeric-conversions + - Data loss when converting from Floating Types to Integer Types +- Numeric Formatting + - Format providers + - Invariant Culture + - Current Culture + - Format Templates + - Standard Format Templates - https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings + - Custom Format Templates - https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings + - Format specifiers + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/objects/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/_index.md new file mode 100644 index 000000000..f8665daf7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/_index.md @@ -0,0 +1,5 @@ +--- +title: "Objects" +linkTitle: "Objects" +description: "Information related to working with Objects." +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-casting.md b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-casting.md new file mode 100644 index 000000000..589b2e011 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-casting.md @@ -0,0 +1,50 @@ +--- +title: "Object Casting" +linkTitle: "Object Casting" +description: "Information regarding casting an object to different data types." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +## Implicit Cast + +TODO + +## Explicit Cast + +TODO + +## Object vs dynamic + +TODO + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-equality.md b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-equality.md new file mode 100644 index 000000000..0e22d4aea --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/object-equality.md @@ -0,0 +1,57 @@ +--- +title: "Object Equality" +linkTitle: "Object Equality" +description: "Information regarding object equality, and what defines two objects as equal." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/statements-expressions-operators/equality-comparisons + +## Value Type vs Reference Type Equality + +TODO: + +### Value Type Equality + +TODO: notes about value equality and a worked through example + +### Reference Type Equality + +TODO: notes about reference equality and a worked through example + +## How {{% ctx %}} compares objects for equality + +TODO: notes about how cortex compares and a worked through example + +Notes:List and Dictionary equality is slightly different to normal equality as it will compare first based on reference and then fall back to value - compared to == .Equals .ReferenceEquals - blocks affected + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/objects/what-is-an-object.md b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/what-is-an-object.md new file mode 100644 index 000000000..e58c95968 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/objects/what-is-an-object.md @@ -0,0 +1,44 @@ +--- +title: "What is an Object?" +linkTitle: "What is an Object?" +description: "Information regarding what an object is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What is the difference between an object and a data type? + - Data Type is the definition, Object is an instance of that definition +- Explain Object Data Type, base foundation of classes + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/_index.md new file mode 100644 index 000000000..9a6db7afd --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/_index.md @@ -0,0 +1,5 @@ +--- +title: "Scopes" +linkTitle: "Scopes" +description: "Information related to working with Scopes." +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/what-is-a-scope.md b/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/what-is-a-scope.md new file mode 100644 index 000000000..22a853071 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/scopes/what-is-a-scope.md @@ -0,0 +1,38 @@ +--- +title: "What is a Scope?" +linkTitle: "What is a Scope?" +description: "Information regarding what a scope is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/tasks/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/tasks/_index.md new file mode 100644 index 000000000..3db070199 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/tasks/_index.md @@ -0,0 +1,7 @@ +--- +title: "Tasks" +linkTitle: "Tasks" +description: "Information related to working with Tasks." +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/_index.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/_index.md new file mode 100644 index 000000000..cd6689495 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Text" +linkTitle: "Text" +description: "Information related to working with Text." +--- diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/casing.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/casing.md new file mode 100644 index 000000000..9a3581df0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/casing.md @@ -0,0 +1,128 @@ +--- +title: "Casing" +linkTitle: "Casing" +description: "Information regarding text casing." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Best Practices + - Comparing strings - do not lower or upper pick a relevant culture or ignore case + +Links: + +- https://learn.microsoft.com/en-us/dotnet/core/extensions/performing-culture-insensitive-string-operations +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/changing-case#compare-strings-of-mixed-case + +## Common types of text casing + +There are many different types of text casing. + +The table below lists some of the most common types of text casing: + +| Name | Example | Notes | +|-----------|----------------------------|-------------| +| lowercase | `"this is lowercase"` | All letters in all words are lower cased. | +| UPPERCASE | `"THIS IS UPPERCASE"` | All letters in all words are capitalized. | +| Title Case | `"This Is Title Case"` | First letter in all words is capitalized, all other letters are lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased; spaces and punctuation are preserved. | +| camelCase | `"thisIsCamelCase"` | First letter in all words (except the first) is capitalized, all other letters are lower cased, and all spaces and punctuation are removed. | +| PascalCase | `"ThisIsCamelCase"` | First letter in all words is capitalized, all other letters are lower cased, and all spaces and punctuation are removed. | + +## Culture Info + +Culture Info specifies the culture-specific casing rules used to determine how the case of text is changed. + +The table below lists the most common supported culture info: + +| Name | Text Value | Description | +|----------|-----------------|-------------| +| Invariant Culture | CultureInfo.InvariantCulture | Used to compare text using culture-sensitive sort rules and the [Invariant Culture][]. Case of the texts is considered when comparing. | +| Current Culture | CultureInfo.CurrentCulture | Used to compare text using culture-sensitive sort rules and the [Current Culture][]. Case of the texts is considered when comparing. | + +In addition to [Invariant][Invariant Culture] and [Current Culture][], there are two other types of culture that can be used: + +- [Specific Cultures][] +- [Custom Cultures][] + +For more information about culture info, please see [CultureInfo][]. + +### Invariant Culture + +For Invariant Culture, the casing rules used to determine how the case of text is changed are not culture-sensitive. + +TODO: + +- Link to Working with Culture -> Invariant Culture +- When to use? If not sure what to choose? +- notes about invariant culture and a worked through example +- From https://learn.microsoft.com/en-us/dotnet/api/system.globalization.textinfo.toupper?view=net-6.0 + +If a security decision depends on a string comparison or a case-change operation, the application should use the InvariantCulture to ensure that the behavior is consistent regardless of the culture settings of the system. However, the invariant culture must be used only by processes that require culture-independent results, such as system services. Otherwise, it produces results that might be linguistically incorrect or culturally inappropriate. + +### Current Culture + +For Current Culture, the casing rules used to determine how the case of text is changed are culture-sensitive and based on the culture of the operating system the flow execution is running on. + +TODO: + +- Link to Working with Culture -> Current Culture +- When to use? If not sure what to choose? +- Best practices - all OSes in cluster should be installed with same OS culture and settings etc. - should also be time sync'd +- Notes about current culture and a worked through example + +### Specific Cultures + +TODO: + +- Talk about how there are a number of specific cultures, each with their own casing rules +- When to use? If not sure what to choose? +- Link to Working with Culture -> Specific Cultures +- For a list of cultures that can be returned on Windows systems see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c under The Language table (`Language tag` defines the code required to create the culture) + +### Custom Cultures + +TODO: + +- Talk about how there can be custom cultures installed, each with their own casing rules +- When to use? If not sure what to choose? +- Link to Working with Culture -> Custom Cultures + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO: + +- Convert to Uppercase +- etc + +### External Documentation + +TODO + +[Current Culture]: {{< ref "#current-culture" >}} +[Invariant Culture]: {{< ref "#invariant-culture" >}} +[Specific Cultures]: {{< ref "#specific-cultures" >}} +[Custom Cultures]: {{< ref "#custom-cultures" >}} + +[CultureInfo]: {{< url path="MSDocs.DotNet.Api.System.Globalization.CultureInfo" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/converting-objects-to-text.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/converting-objects-to-text.md new file mode 100644 index 000000000..289cbf121 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/converting-objects-to-text.md @@ -0,0 +1,87 @@ +--- +title: "Converting Objects To Text" +linkTitle: "Converting Objects To Text" +description: "Information regarding converting objects to their text representation." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +### Using Blocks + +TODO: + +- Explain that blocks can be used - maybe with examples or link to examples within the block documentation + - Format Text With Value + - Format Text With Values + - Join Text + - Convert Date Time To Text + - Convert Object To Text - need to make it clear how this works - does tostring and if tostring returns class name does json serialisation + - Convert Object To Json - need to make it clear how this works - does json serialisation + +### Using Expressions + +#### ToString() + +TODO: + +- .ToString() - talk about that some objects will just return their name, text formatting format providers etc. +- Convert.ToString() +- Examples and where to find in Data Types documentation + +#### String interpolation + +See [Interpolated Strings][]. + +#### String.Format() + +TODO: String.Format + +## Remarks + +### Known Limitations + +#### Support for {{}} is Missing + +Using `{{VariableName}}` expression syntax to convert a [variable][] to its [String][] representation is currently not supported. + +It is possible to convert a [variable][] to its string representation within an [expression][] by using the `ToString()` [method][] (e.g. `($)VariableName.ToString()`) + +In future this limitation may be removed. + +[variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} +[expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.Expressions" >}} +[method]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MethodExpressions" >}} +[Interpolated Strings]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.InterpolatedStrings" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO: + +- Format Text With Value +- Format Text With Values +- Join Text +- Convert Date Time To Text +- Convert Object To Text - need to make it clear how this works - does tostring and if tostring returns class name does json serialisation +- Convert Object To Json - need to make it clear how this works - does json serialisation + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/empty-text-and-whitespace.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/empty-text-and-whitespace.md new file mode 100644 index 000000000..b96d91918 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/empty-text-and-whitespace.md @@ -0,0 +1,51 @@ +--- +title: "Empty Text and Whitespace" +linkTitle: "Empty Text and Whitespace" +description: "Information regarding empty text and whitespace." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What is an Empty Text? +- What is Whitespace? +- Difference between empty text and whitespace + +## Empty Text + +TODO: + +- How to create an empty text - `""` or `String.Empty` + +## Whitespace + +https://learn.microsoft.com/en-us/dotnet/api/system.char.iswhitespace?view=net-5.0#System_Char_IsWhiteSpace_System_Char_ and textual representation \t \r \n etc. + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/encoding.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/encoding.md new file mode 100644 index 000000000..0c7b295a5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/encoding.md @@ -0,0 +1,49 @@ +--- +title: "Encoding" +linkTitle: "Encoding" +description: "Information regarding text encoding." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Available encodings +- How to define them/use them + - Different ways to specify encoding: + - Encoding encoding = Encoding.GetEncoding(20127); + - Encoding encoding = new ASCIIEncoding(); + - Encoding encoding = Encoding.ASCII; +- Talk about encode/decode text blocks including base64/url/hex/html/utf8/base64url + +Links: + +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/character-encoding-introduction + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/equality.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/equality.md new file mode 100644 index 000000000..51142f784 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/equality.md @@ -0,0 +1,126 @@ +--- +title: "Equality" +linkTitle: "Equality" +description: "Information regarding text equality." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- Best Practices + - Use Ordinal to remove ambiguity and increase performance + - Comparing strings - do not lower or upper pick a relevant culture or ignore case + +Links: + +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/changing-case#compare-strings-of-mixed-case + +## Comparison Types + +Comparison Types specify the rules used to determine whether two pieces of text match. + +The table below lists the supported comparison types: + +| Name | Text Value | Numeric Value | Description | +|----------|------------|---------------|-------------| +| [Ordinal][] | StringComparison.Ordinal | 4 | Used to compare text using ordinal sort rules. Case of the texts is considered when comparing. | +| [Ordinal Ignore Case][] | StringComparison.OrdinalIgnoreCase | 5 | Used to compare text using ordinal sort rules. Case of the texts is ignored when comparing. | +| [Invariant Culture][] | StringComparison.InvariantCulture | 2 | Used to compare text using culture-sensitive sort rules and the invariant culture. Case of the texts is considered when comparing. | +| [Invariant Culture Ignore Case][] | StringComparison.InvariantCultureIgnoreCase | 3 | Used to compare text using culture-sensitive sort rules and the invariant culture. Case of the texts is ignored when comparing. | +| [Current Culture][] | StringComparison.CurrentCulture | 0 | Used to compare text using culture-sensitive sort rules and the current culture. Case of the texts is considered when comparing. | +| [Current Culture Ignore Case][] | StringComparison.CurrentCultureIgnoreCase | 1 | Used to compare text using culture-sensitive sort rules and the current culture. Case of the texts is ignored when comparing. | + +For more information about comparison types, please see [StringComparison][]. + +TODO: Consider moving sections below into the StringComparison Data Type documentation and removed from this page + +### Ordinal + +TODO: + +- When to use? If not sure what to choose? +- Ordinal sort rules +- notes about ordinal and a worked through example + +### Ordinal Ignore Case + +TODO: + +- When to use? If not sure what to choose? +- Link to Ordinal sort rules, only difference is that it doesn't consider casing when comparing characters +- notes about ordinal ignore case and a worked through example + +### Invariant Culture + +TODO: + +- When to use? If not sure what to choose? +- Link to Culture -> Invariant Culture +- Invariant Culture rules +- notes about invariant culture and a worked through example + +### Invariant Culture Ignore Case + +TODO: + +- When to use? If not sure what to choose? +- Link to Culture -> Invariant Culture +- Link to Invariant Culture sort rules, only difference is that it doesn't consider casing when comparing characters +- notes about invariant culture ignore case and a worked through example + +### Current Culture + +TODO: + +- When to use? If not sure what to choose? +- Link to Culture -> Current Culture +- Current Culture rules +- notes about current culture and a worked through example + +### Current Culture Ignore Case + +TODO: + +- When to use? If not sure what to choose? +- Link to Culture -> Current Culture +- Link to Current Culture sort rules, only difference is that it doesn't consider casing when comparing characters +- notes about current culture ignore case and a worked through example + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO + +[Current Culture]: {{< ref "#current-culture" >}} +[Current Culture Ignore Case]: {{< ref "#current-culture-ignore-case" >}} +[Invariant Culture]: {{< ref "#invariant-culture" >}} +[Invariant Culture Ignore Case]: {{< ref "#invariant-culture-ignore-case" >}} +[Ordinal]: {{< ref "#ordinal" >}} +[Ordinal Ignore Case]: {{< ref "#ordinal-ignore-case" >}} + +[StringComparison]: {{< url path="MSDocs.DotNet.Api.System.StringComparison" >}} diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/formatting.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/formatting.md new file mode 100644 index 000000000..958199470 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/formatting.md @@ -0,0 +1,113 @@ +--- +title: "Formatting" +linkTitle: "Formatting" +description: "Information regarding text formatting." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What formatting is +- How to format text + - Blocks + - Expression +- How does text formatting use DateTime Formatting and Number Formatting? + - Link to Working With -> Date and Time -> Date and Time Formatting + - Link to Working With -> Number -> Number Formatting + +## Using Blocks + +TODO: + +- Explain that blocks can be used - maybe with examples or link to examples within the block documentation + - Convert Object to Text + - Format Text with Value + - Format Text with Values + +## Using Expressions + +TODO: How to format using an expression + +### String Interpolation + +TODO: + +- mention that convert object to text is close to behaviour of string interpolation, but not everything is covered - e.g. no expression support or indexing - recommendation is to use string.interpolation inline as more powerful and saves block licensing + +## Format Providers + +TODO: + +- what are they +- ways of creating + - CultureInfo.InvariantCulture + - CultureInfo.CurrentCulture + - new CultureInfo("") + - new CultureInfo("en-GB") + +## Format Templates + +TODO: + +- Find C# link +- Talk about what a template is and how format parameters are used (e.g. `"{0}"`) +- curly brackets need to be escaped when using the $ and $@ prefixes + +## Format Specifiers + +TODO: + +- Add table of format specifiers + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#Starting + +TODO: Control formatting + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#control-formatting + +TODO: Control spacing + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#control-spacing + +TODO: Control alignment + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#control-alignment + +TODO: Composite formatting + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#the-format-method-in-brief + +TODO: Format Item + +- https://learn.microsoft.com/en-us/dotnet/api/system.string.format?view=net-6.0#the-format-item + +TODO: Anything else relevant on formatting links above + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/pattern-matching-syntax.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/pattern-matching-syntax.md new file mode 100644 index 000000000..4902f3664 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/pattern-matching-syntax.md @@ -0,0 +1,48 @@ +--- +title: "Pattern Matching Syntax" +linkTitle: "Pattern Matching Syntax" +description: "Information regarding pattern matching syntax." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO + +- What is pattern matching? + - how is it different to contains or regex +- Pattern matching can only be used in blocks +- `*` is 0 or more +- `?` is 0 or 1 +- to use these as literals use `\\*` `\\?` +- Common pattern matching + - `**/*.ext` (Check that this works) + - Common file extensions to search for, how to search for them `*.txt`, `*.pdf` + - Link to Files and Folders for list of common extensions + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/regex-syntax.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/regex-syntax.md new file mode 100644 index 000000000..8e8caee71 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/regex-syntax.md @@ -0,0 +1,216 @@ +--- +title: "Regex Syntax" +linkTitle: "Regex Syntax" +description: "Information regarding .Net regex syntax." +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What is regex matching? + - how is it different to contains or pattern matching +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expressions +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference +- Common regex expressions + - urls, emails, etc + - https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-example-scanning-for-hrefs + - and subsequent links +- State that we specify a timeout to prevent dos attacks +- Talk about no current support for old g2 syntax - may add in future + +TODO: Options + +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-options +- https://learn.microsoft.com/en-us/dotnet/standard/base-types/miscellaneous-constructs-in-regular-expressions + +Links: + +- Regex Best Practices - https://learn.microsoft.com/en-us/dotnet/standard/base-types/best-practices + +### Character Classes + +TODO: + +- Include information about any builtin snippets for each regex + +A character class matches any of a set of characters. Character classes include the language elements listed in the following table. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `[characters]` | Matches any character found in characters. | `[oz]` | o in Cortex | +| `[^characters]` | Matches any character not found in characters. | `[^oz]` | C, r, t, e, x in Cortex | +| `[first-last]` | Matches any character in the range of characters from first to last. | `[A-C]` | C in Cortex | +| `.` | Wildcard. Matches any character except \n. | `C.r` | Cor in Cortex | +| `\p{category}` | Matches any character in a category of Unicode characters, specified by category. To see what you can use for category, please check the supported Unicode general categories and the supported named blocks. | `\p{Lu}` | C in Cortex | +| `\P{category}` | Matches any character not in a category of Unicode characters, specified by category. To see what you can use for category, please check the supported Unicode general categories, and the supported named blocks. | `\P{Lu}` | o, r, t, e, x in Cortex | +| `\w` | Matches any letter, decimal digit, or an underscore. | `\w` | C, o, r, t, e, x in Cortex ! | +| `\W` | Matches any character except a letter, decimal digit, or an underscore. | `\W` | ! in Cortex ! | +| `\s` | Matches any white-space character. | `\w\s` | x  in Cortex ! | +| `\S` | Matches any character except a white-space character. | `\s\S` |  ! in Cortex ! | +| `\d` | Matches any decimal digit. | `\d` | 7 in Cortex 7! | +| `\D` | Matches any character except a decimal digit. | `\D` | C, o, r, t, e, x,  , ! in Cortex 7! | + +https://learn.microsoft.com/en-us/dotnet/standard/base-types/character-classes-in-regular-expressions#SupportedUnicodeGeneralCategories +https://learn.microsoft.com/en-us/dotnet/standard/base-types/character-classes-in-regular-expressions#supported-named-blocks + +### Character Escapes + +TODO: + +- Include information about any builtin snippets for each regex + +The following table lists the character escapes supported by regular expressions in .NET. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `\r` | Matches a carriage return. | `\r\n(\w+)` | \r\nCortex in \r\nCortex with\na new line | +| `\n` | Matches a newline. | `\r\n(\w+)` | \r\nCortex in \r\nCortex with\na new line | +| `\t` | Matches a tab. | `(\w+)\t` | Cortex1\t, Cortex2\t in Cortex1\tCortex2\t | +| `[\b]` | Matches a backspace. Note that it must be enclosed in brackets to have this meaning. | `[\b]{3,}` | \b\b\b\b in \b\b\b\b | +| `\f` | Matches a form feed. | `[\f]{2,}` | \f\f\f in \f\f\f | +| `\e` | Matches an escape. | `\e` | \x001B in \x001B | +| `\v` | Matches a vertical tab. | `[\v]{2,}` | \v\v\v in \v\v\v | +| `\a` | Matches the bell character. | `\a` | \u0007 in Cortex '\u0007' | +| `\octal` | Matches a character, where octal is the octal representation of that character. | `\w\040\w` | x C in Cortex Cortex | +| `\xhex` | Matches a character, where hex is the two-digit hexadecimal representation of that character. | `\w\x20\w` | x C in Cortex Cortex | +| `\uunicode` | Matches a Unicode character, where unicode is the four digit hexadecimal representation of that Unicode character. | `\w\u0020\w` | x C in Cortex Cortex | +| `\ccharacter` | Matches an ASCII control character specified by character. | `\cC` | \x0003 in \x0003 | + +### Quantifiers + +TODO: + +- Include information about any builtin snippets for each regex + +A quantifier specifies how many instances of the previous element (which can be a character, a group, or a character class) must be present in the input string for a match to occur. Quantifiers include the language elements listed in the following table. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `*` | Matches previous element zero or more times. | `co*rtex` | crtex, cortex, coortex, coooortex in crtex cortex coortex coooortex | +| `+` | Matches previous element one or more times. | `co+rtex` | cortex, coortex, coooortex in crtex cortex coortex coooortex | +| `?` | Matches previous element zero or one times. | `co?rtex` | crtex, cortex in crtex cortex coortex coooortex | +| `{n}` | Matches previous element exactly n times. | `co{2}rtex` | coortex in crtex cortex coortex coooortex | +| `{n,}` | Matches previous element at least n times. | `co{2,}rtex` | coortex, coooortex in crtex cortex coortex coooortex | +| `{n,m}` | Matches previous element at least n times and at most m times. | `co{1,2}rtex` | cortex, coortex in crtex cortex coortex coooortex | +| `*?` | Matches previous element zero or more times, but as few times as possible. | `cort(ex)*?` | cort in cortexexex | +| `+?` | Matches previous element one or more times, but as few times as possible. | `cort(ex)+?` | cortex in cortexexex | +| `??` | Matches previous element zero or one time, but as few times as possible. | `cort(ex)??` | cort in cortexexex | +| `{n,}?` | Matches previous element at least n times, but as few times as possible. | `cort(ex){2,}?` | cortexex in cortexexex | +| `{n,m}?` | Matches previous element at least n times and at most m times, but as few times as possible. | `cort(ex){1,3}?` | cortex in cortexexex | + +### Anchors + +TODO: + +- Include information about any builtin snippets for each regex + +Anchors cause a match to succeed or fail depending on the current position in the string. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `^` | Matches the beginning of the input. | `^\w{3}` | Cor in Cortex | +| `$` | Matches the end of the input, or the point before a final \n at the end of the input. | `\w{3}$` | tex in Cortex | +| `\A` | Matches the beginning of the input. Identical to ^, except it is unaffected by the multi-line option. | `\A\w{3}` | Cor in Cortex | +| `\z` | Matches the end of the input, without exception. | `\w{3}\z` | tex in Cortex | +| `\Z` | Matches the end of the input, or the point before a final \n at the end of the input. Identical to $, except it is unaffected by the multi-line option. | `\w{3}\Z` | tex in Cortex | +| `\G` | Matches the point that the previous match ended. Used to find contiguous matches. | `\G\D*\s` | Cortex , reads  in Cortex reads 7 files | +| `\b` | Matches any word boundary. Specifically, any point between a \w and a \W. | `\b\w+\s\w+\b` | Cortex reads, Cortex writes in Cortex reads Cortex writes | +| `\B` | Matches any point that is not a word boundary. Specifically, any point not between a \w and a \W. | `\Brt\w*\b` | rtex, rtex in Cortex reads Cortex writes | + +### Grouping Constructs + +TODO: + +- Include information about any builtin snippets for each regex + +Grouping constructs delineate sub-expressions of a regular expression and typically capture sub-strings of an input string. Grouping constructs include the language elements listed in the following table. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `(subpattern) `| Captures subpattern as an unnamed group. | `(\w)\1` | oo in Coortex | +| `(?subpattern)` | Captures subpattern as a named group specified by name. | `(?\w)\k` | oo in Coortex | +| `(?subpattern)` | Balancing group definition. This allows nested constructs to be matched, such as parentheses or HTML tags. The previously defined group to balance against is specified by previous. Captures subpattern as a named group specified by name, or name can be omitted to capture as an unnamed group. | `(((?)[^<]*)+([^<]*(?))+)+(?(open)(?!))` | <span>Cortex this is included</span>, <span>Cortex this is included too</span> in not included <span>Cortex this is included</span> not included either <span>Cortex this is included too</span> | +| `(?:subpattern)` | Non-capturing group. Allows the use of parentheses without subpattern being captured into a group. | `Cortex\s(?:include)?` | Cortex include, Cortex  in Cortex include Cortex not include | +| `(?enabled-disabled:subpattern)` | Allows subpattern to be matched with different options than the rest of the pattern. Any inline option characters in enabled or disabled will enable or disable specific options, respectively. To see what inline option characters are available, please check the regular expressions options. | `(?i:c\|v)(ortex)` | cortex, Cortex, Vortex in cortex Cortex Vortex CORTEX | +| `(?=subpattern)` | Zero-width positive look-ahead assertion. Continues matching only if subpattern matches on the right. | `\w+(?=ex\b)` | Cort, Vort in Cortex Vortex Balloon | +| `(?!subpattern)` | Zero-width negative look-ahead assertion. Continues matching only if subpattern does not match on the right. | `\b\w+\.(?!exe)\w+\b` | cortex.jpg, cortex.html in cortex.jpg cortex.html .*.html cortex.exe | +| `(?<=subpattern)` | Zero-width positive look-behind assertion. Continues matching only if subpattern matches on the left. | `(?<=\(\$\))\w+` | variable, 22 in ($)variable ($)22 ($)-- | +| `(?subpattern)` | Prevents backtracking over subpattern, which can improve performance. | `[cv](?>o+r+)` | cor, coor, vor in cortex coortex vortex gortex | + +### Back-reference Constructs + +TODO: + +- Include information about any builtin snippets for each regex + +A back-reference allows a previously matched sub-expression to be identified subsequently in the same regular expression. The following table lists the back-reference constructs supported by regular expressions in .NET. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `\number` | Matches the value of a previously captured group, specified by number. | `\b(\w)\w*\1\b` | xcortex, that in Finds all words like xcortex that start and end with the same letter | +| `\k` | Matches the value of a previously captured named group, specified by name. | `(?\p{P})\w+\k` | !cortex!, ?cortex? in !cortex! ?cortex? XcortexX | + +### Alternation Constructs + +TODO: + +- Include information about any builtin snippets for each regex + +Alternation constructs changes a regular expression to enable either/or matching. These constructs include the language elements listed in the following table. + +| Syntax | Description | Pattern | Matches | +|---|---|---|---| +| `\|` | Functions as a logical or. Matches any elements it separates. | `(c\|v)ortex` | cortex, vortex in cortex vortex xortex | +| `(?(subpattern)yes\|no)` | Treats subpattern as a zero-width assertion to check if it matches. If so, attempts to match with the yes subpattern. Otherwise, tries the no subpattern. The \|no part is optional. | `\b(?(\w+tez\b)\w{3}\|cortex)` | cortex, cor in cortex cortez vortex | +| `(?(group)yes\|no)` | Checks if a previously defined group was successfully captured, specified by group, which can be a number or a name for a named group. If so, attempts to match with the yes subpattern. Otherwise, tries the no subpattern. The \|no part is optional. | `(?(\(\$\)))\w+\|'\w+'` | cortex, 'cortex' in ($)cortex 'cortex' | + +### Substitutions + +TODO: + +- Include information about any builtin snippets for each regex + +Substitutions are regular expression language elements supported in replacement patterns. + +| Syntax | Description | Pattern | Replacement | Result | +|---|---|---|---|---| +| `$number` | Substitutes the value of a group, specified by number. | `\b(\w+)(\s)(\w+)\b` | `$3$2$1` | Cortex Great becomes Great Cortex | +| `${name}` | Substitutes the value of a named group, specified by name. | `\b(?\w+)(\s)(?\w+)\b` | `${word2} ${word1}` | Cortex Great becomes Great Cortex | +| `$$` | Substitutes the $ character. | `\b(dollar)` | `$$` | (dollar)name becomes ($)name | +| `$&` | Substitutes the entire match. | `\w+` | `\*\*$&\*\*` | Cortex becomes \*\*Cortex\*\* | +| ``$` `` | Substitutes all input text found before the match. | `#+` | ``$` `` | Co##rtex becomes CoCortex | +| `$'` | Substitutes all input text found after the match. | `#+` | `$'` | Cort##ex becomes Cortexex | +| `$+` | Substitutes the last group captured. | `Co(r)` | `$+` | CoCortex becomes Cortex | +| `$_` | Substitutes the entire input. | `\w+?` | `$_`  | Cortex becomes Cortex Cortex Cortex Cortex Cortex Cortex  | + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO: List blocks which support using regex + +TODO: All blocks which support regex should link back here from the properties that support it + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Concepts/working-with/text/what-is-text.md b/content/en/docs/2024.9/Reference/Concepts/working-with/text/what-is-text.md new file mode 100644 index 000000000..0fee94a8e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Concepts/working-with/text/what-is-text.md @@ -0,0 +1,68 @@ +--- +title: "What is Text?" +linkTitle: "What is Text?" +description: "Information regarding what text is." +weight: 1 +--- + +# {{% param title %}} + +{{< workinprogress >}} + +## Summary + +TODO: + +- What is text + - null, string.Empty, and whitespace +- Difference between string and char +- Operators and Comparisons + - https://learn.microsoft.com/en-us/dotnet/standard/base-types/basic-string-operations + - Concatenation + - Equality + - Casing + - Ordinal + - Invariant Culture + - Current Culture + - https://learn.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings + - LiteralText vs Regex vs PatternMatching + - Links to LiteralText + - Links to Regex + - Links to PatternMatching +- Parsing text to a number +- String Formatting + - Date Formatting + - Number Formatting +- Encoding +- Immutability of strings https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/strings/#immutability-of-strings +- Literal, Verbatim and Interpolated Strings + - String escape sequences https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/strings/#string-escape-sequences +- Substrings and Indexing + +Links: + +- https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/strings/ + +## Remarks + +### Known Limitations + +TODO + +## See Also + +### Related Concepts + +TODO + +### Related Data Types + +TODO + +### Related Blocks + +TODO + +### External Documentation + +TODO diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/_index.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/_index.md new file mode 100644 index 000000000..2bf5aaf81 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/_index.md @@ -0,0 +1,5 @@ +--- +title: "Property" +linkTitle: "Property" +description: "Exceptions related to issues with Block Properties" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-item-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-item-exception.md new file mode 100644 index 000000000..1da6faad4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-item-exception.md @@ -0,0 +1,106 @@ +--- +title: "PropertyContainsNullItemException" +linkTitle: "PropertyContainsNullItemException" +description: "The exception thrown when a property is provided with a value that contains at least one item that is `null`." +--- + +# {{% param title %}} + +

(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 +"'' contains at least one null value; it must only contain values that are not null. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property. + +#### How to fix + +Ensure the value provided for the [property][] named `` does not contain items that are `null`. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyContainsNullItemException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +* `` will be replaced with the name of the [property][]. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, only the `` has been included in the exception. In future, we will look to include the name and Id of the [block][], the id, 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][] + +### Related Concepts + +* [Blocks][block] +* [Block Properties][property] +* [Exceptions][] + +### Related Blocks + +* Tasks + * [Cancel All Tasks][] + * [Wait For All Tasks][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Cancel All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.CancelTask.CancelAllTasksBlock.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-or-empty-item-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-or-empty-item-exception.md new file mode 100644 index 000000000..a3a05b726 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-contains-null-or-empty-item-exception.md @@ -0,0 +1,104 @@ +--- +title: "PropertyContainsNullOrEmptyItemException" +linkTitle: "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." +--- + +# {{% param title %}} + +

(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 +"'' contains at least one null or empty value; it must only contain values that are not null or empty. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property. + +#### How to fix + +Ensure the value provided for the [property][] named `` does not contain items that are either `null` or empty. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyContainsNullOrEmptyItemException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +* `` will be replaced with the name of the [property][]. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, only the `` has been included in the exception. In future, we will look to include the name and Id of the [block][], the id, 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][] + +### Related Concepts + +* [Blocks][block] +* [Block Properties][property] +* [Exceptions][] + +### Related Blocks + +* Exceptions + * [Handle Block Exception Matching Type Names][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Handle Block Exception Matching Type Names]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleBlock.HandleBlockExceptionMatchingTypeNames.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[block]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-empty-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-empty-exception.md new file mode 100644 index 000000000..89bd5b29e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-empty-exception.md @@ -0,0 +1,239 @@ +--- +title: "PropertyEmptyException" +linkTitle: "PropertyEmptyException" +description: "The exception thrown when a property is provided with an empty value, but a non-empty value is required." +--- + +# {{% param title %}} + +

(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 +"'' is empty; it must be provided a value. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property. + +#### How to fix + +Ensure the value provided for the [property][] named `` is not [empty][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyEmptyException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +* `` will be replaced with the name of the [property][]. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, only the `` has been included in the exception. In future, we will look to include the name and Id of the [block][], the id, 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][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +* Data + * [Execute Data Command][] +* Data Storage + * [Create Collection][] + * [Delete Collection][] + * [Delete Data With Key][] + * [Read Data With Key][] + * [Wait For Collection To Exist][] + * [Wait For Collection To Not Exist][] + * [Wait For Key In Collection To Be Set][] + * [Wait For Key In Collection To Contain Value][] + * [Wait For Key In Collection To Exist][] + * [Wait For Key In Collection To Not Exist][] + * [Write Data With Key][] +* Date & Time + * [Convert Text To Date Time][] +* Email + * [Send Email Using SMTP Server][] +* Exceptions + * [Handle Block Exception Matching Messages][] + * [Handle Block Exception Matching Type Name][] + * [Handle Block Exception Matching Type Names][] +* Files & Folders + * [Copy File][] + * [Copy Files][] + * [Copy Folder][] + * [Copy Folders][] + * [Create Folder][] + * [Create Folders][] + * [Delete File][] + * [Delete Files][] + * [Delete Folder][] + * [Delete Folders][] + * [Duplicate Folder][] + * [Get File Information][] + * [Get Folder Content][] + * [Get Folder Information][] + * [Move File][] + * [Move Files][] + * [Move Folder][] + * [Move Folders][] + * [Read All Lines][] + * [Read All Text][] + * [Rename Folder][] + * [Search File][] + * [Search Files][] + * [Write All Lines][] + * [Write All Text][] +* Json + * [Convert Json To Object][] +* Lists + * [Get Item At Beginning][] + * [Get Item At End][] + * [Set Item At Beginning][] + * [Set Item At End][] + * [Set Items At Beginning][] + * [Set Items At End][] + * [Set Items At Index][] +* Queues + * [Dequeue Item][] + * [Dequeue Items][] + * [Peek Item][] +* Tasks + * [Cancel All Tasks][] + * [Wait For All Tasks][] +* Xml + * [Convert Structure To Xml][] + * [Convert Xml To Structure][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Execute Data Command]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.MainDoc" >}} + +[Convert Text To Date Time]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTime.MainDoc" >}} + +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} +[Delete Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc">}} +[Delete Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.MainDoc">}} +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Wait For Collection To Exist]: {{< url path="Cortex.Reference.Blocks.DataStorage.WaitForCollection.WaitForCollectionToExistBlock.MainDoc">}} +[Wait For Collection To Not Exist]: {{< url path="Cortex.Reference.Blocks.DataStorage.WaitForCollection.WaitForCollectionToNotExistBlock.MainDoc">}} +[Wait For Key In Collection To Be Set]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToBeSetBlock.MainDoc">}} +[Wait For Key In Collection To Contain Value]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToContainValueBlock.MainDoc">}} +[Wait For Key In Collection To Exist]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToExistBlock.MainDoc">}} +[Wait For Key In Collection To Not Exist]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToNotExistBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[Send Email Using SMTP Server]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.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" >}} + +[Copy File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFile.CopyFile.MainDoc" >}} +[Copy Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFile.CopyFiles.MainDoc" >}} +[Copy Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolder.MainDoc" >}} +[Copy Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolders.MainDoc" >}} +[Create Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CreateFolder.CreateFolder.MainDoc" >}} +[Create Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CreateFolder.CreateFolders.MainDoc" >}} +[Delete File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFile.DeleteFile.MainDoc" >}} +[Delete Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFile.DeleteFiles.MainDoc" >}} +[Delete Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFolder.DeleteFolder.MainDoc" >}} +[Delete Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFolder.DeleteFolders.MainDoc" >}} +[Duplicate Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.DuplicateFolder.MainDoc" >}} +[Get File Information]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFileInformation.GetFileInformation.MainDoc" >}} +[Get Folder Content]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFolderContent.GetFolderContent.MainDoc" >}} +[Get Folder Information]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFolderInformation.GetFolderInformation.MainDoc" >}} +[Move File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFile.MoveFile.MainDoc" >}} +[Move Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFile.MoveFiles.MainDoc" >}} +[Move Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolder.MainDoc" >}} +[Move Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolders.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" >}} +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.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" >}} + +[Convert Json To Object]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertJsonToObject.MainDoc" >}} + +[Get Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtBeginning.MainDoc" >}} +[Get Item At End]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtEnd.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 Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtBeginning.MainDoc" >}} +[Set Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtEnd.MainDoc" >}} +[Set Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndex.MainDoc" >}} + +[Dequeue Item]: {{< url path="Cortex.Reference.Blocks.Queues.DequeueItem.DequeueItemBlock.MainDoc" >}} +[Dequeue Items]: {{< url path="Cortex.Reference.Blocks.Queues.DequeueItem.DequeueItemsBlock.MainDoc" >}} +[Peek Item]: {{< url path="Cortex.Reference.Blocks.Queues.PeekItem.PeekItemBlock.MainDoc" >}} + +[Convert Structure To Xml]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml.MainDoc" >}} +[Convert Xml To Structure]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure.MainDoc" >}} + +[Cancel All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.CancelTask.CancelAllTasksBlock.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.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" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[empty]: {{< url path="Cortex.Reference.Glossary.A-E.Empty" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-item-count-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-item-count-exception.md new file mode 100644 index 000000000..5b3f1b267 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-item-count-exception.md @@ -0,0 +1,121 @@ +--- +title: "PropertyItemCountException" +linkTitle: "PropertyItemCountException" +description: "The exception thrown when the values provided for two properties are expected to contain the same number of items, but don't." +--- + +# {{% param title %}} + +

(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 '' provided. +There are items in '' and items in ''. +The number of items in '' must be the same as the number of items in ''. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the first property. +* `` is the name of the second property. +* `` is the count of items in the first property. +* `` is the count of items in the second property. + +#### How to fix + +Ensure that the value provided for each of the two [properties][] contains the same number of items. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyItemCountException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +* `` will be replaced with the name of the first property. +* `` will be replaced with the name of the second property. +* `` will be replaced with the count of items in the first property. +* `` will be replaced with the count of items in the second property. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, the `` and `` have been included in the exception. In future, we will look to include the name and Id of the [block][], the id, name and value of the [property][properties], as well as allowing the exception to contain a link to take you directly to the offending value. + +## See Also + +### Related Data Types + +* [String][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +* Dictionaries + * [Set Items With Keys][] + * [Set Items With Values][] +* Lists + * [Set Items At Indexes][] + * [Set Items With Values][List Set Items With Values] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Set Items With Keys]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithKeys.MainDoc" >}} +[Set Items With Values]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithValues.MainDoc" >}} + +[Set Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndexes.MainDoc" >}} +[List Set Items With Values]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsWithValues.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" >}} +[properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-null-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-null-exception.md new file mode 100644 index 000000000..964d3bcd5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-null-exception.md @@ -0,0 +1,403 @@ +--- +title: "PropertyNullException" +linkTitle: "PropertyNullException" +description: "The exception thrown when a property is provided with a `null` value, but a non-null value is required." +--- + +# {{% param title %}} + +

(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 +"'' is null; it must be provided with a non-null value. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property. + +#### How to fix + +Provide a non-null value for the [property][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyNullException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +* `` will be replaced with the name of the [property][]. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +Currently, only the `` has been included in the exception. In future, we will look to include the name and Id of the [block][], the id, 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][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Exceptions][] + +### Related Blocks + +* Data + * [Execute Data Command][] +* Data Storage + * [Create Collection][] + * [Delete Collection][] + * [Delete Data With Key][] + * [Read Data With Key][] + * [Wait For Collection To Exist][] + * [Wait For Collection To Not Exist][] + * [Wait For Key In Collection To Be Set][] + * [Wait For Key In Collection To Contain Value][] + * [Wait For Key In Collection To Exist][] + * [Wait For Key In Collection To Not Exist][] + * [Write Data With Key][] +* Date & Time + * [Convert Text To Date Time][] +* Dictionaries + * [Add Item With Key][] + * [Contains Item With Key And Value][] + * [Contains Item With Key][] + * [Contains Item With Value][] + * [Contains Items With Keys][] + * [Contains Items With Values][] + * [Get Count Of All Items][] + * [Get Count Of Items With Value][] + * [Get Counts Of Items With Values][] + * [Get All Items][] + * [Get All Keys][] + * [Get Item With Key][] + * [Get Items With Key][] + * [Remove All Items][] + * [Remove Item With Key][] + * [Remove Item With Value][] + * [Remove Items With Key][] + * [Remove Items With Keys][] + * [Remove Items With Value][] + * [Remove Items With Values][] + * [Set All Items][] + * [Set Item With Key][] + * [Set Item With Value][] + * [Set Items With Key][] + * [Set Items With Keys][] + * [Set Items With Value][] + * [Set Items With Values][] +* Exceptions + * [Handle Block Exception Matching Messages][] + * [Handle Block Exception Matching Type Name][] + * [Handle Block Exception Matching Type Names][] + * [Rethrow Exception][] +* Email + * [Send Email Using SMTP Server][] +* Files & Folders + * [Copy File][] + * [Copy Files][] + * [Copy Folder][] + * [Copy Folders][] + * [Create Folder][] + * [Create Folders][] + * [Delete File][] + * [Delete Files][] + * [Delete Folder][] + * [Delete Folders][] + * [Duplicate Folder][] + * [Get File Information][] + * [Get Folder Content][] + * [Get Folder Information][] + * [Move File][] + * [Move Files][] + * [Move Folder][] + * [Move Folders][] + * [Read All Lines][] + * [Read All Text][] + * [Rename Folder][] + * [Search File][] + * [Search Files][] + * [Write All Lines][] + * [Write All Text][] +* Json + * [Convert Json To Object][] +* Lists + * [Add Item At Beginning][] + * [Add Item At End][] + * [Add Item At Index][] + * [Add Items At Beginning][] + * [Add Items At End][] + * [Add Items At Index][] + * [Contains Item With Value][List Contains Item With Value] + * [Contains Items With Values][List Contains Items With Values] + * [Get Count Of All Items][List Get Count Of All Items] + * [Get Count Of Items With Value][List Get Count Of Items With Value] + * [Get Count Of Items With Values][List Get Count Of Items With Values] + * [Get Index Of Item With Value][] + * [Get Indexes Of Items With Value][] + * [Get Item At Beginning][] + * [Get Item At End][] + * [Get Item At Index][] + * [Get Items At Beginning][] + * [Get Items At End][] + * [Get Items At Index][] + * [Get Items At Indexes][] + * [Remove All Items][List Remove All Items] + * [Remove Duplicate Items][] + * [Remove Item At Beginning][] + * [Remove Item At End][] + * [Remove Item At Index][] + * [Remove Item With Value][List Remove Item With Value] + * [Remove Items At Beginning][] + * [Remove Items At End][] + * [Remove Items At Index][] + * [Remove Items At Indexes][] + * [Remove Items With Value][List Remove Items With Value] + * [Remove Items With Values][List Remove Items With Values] + * [Set All Items][List Set All Items] + * [Set Item At Beginning][] + * [Set Item At End][] + * [Set Item At Index][] + * [Set Item With Value][List Set Item With Value] + * [Set Items At Beginning][] + * [Set Items At End][] + * [Set Items At Index][] + * [Set Items At Indexes][] + * [Set Items With Value][List Set Items With Value] + * [Set Items With Values][List Set Items With Values] +* Logs + * [Log Event][] +* Loops + * [For Loop][] +* Objects + * [Convert Object To Text][] +* Queues + * [Dequeue Item][] + * [Dequeue Items][] + * [Enqueue Item][] + * [Enqueue Items][] + * [Get Count Of All Items][Queues Get Count Of All Items] + * [Peek Item][] + * [Remove All Items][Q Remove All Items] +* Tasks + * [Cancel Task][] + * [Cancel All Tasks][] + * [Wait For Task][] + * [Wait For All Tasks][] +* Text + * [Contains All Text][] + * [Contains Any Text][] + * [Format Text With Values][] + * [Join Text][] +* Xml + * [Convert Structure To Xml][] + * [Convert Xml To Structure][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Execute Data Command]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.MainDoc" >}} + +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} +[Delete Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc">}} +[Delete Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.MainDoc">}} +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Wait For Collection To Exist]: {{< url path="Cortex.Reference.Blocks.DataStorage.WaitForCollection.WaitForCollectionToExistBlock.MainDoc">}} +[Wait For Collection To Not Exist]: {{< url path="Cortex.Reference.Blocks.DataStorage.WaitForCollection.WaitForCollectionToNotExistBlock.MainDoc">}} +[Wait For Key In Collection To Be Set]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToBeSetBlock.MainDoc" >}} +[Wait For Key In Collection To Contain Value]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToContainValueBlock.MainDoc">}} +[Wait For Key In Collection To Exist]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToExistBlock.MainDoc">}} +[Wait For Key In Collection To Not Exist]: {{< url path = "Cortex.Reference.Blocks.DataStorage.WaitForKeyInCollection.WaitForKeyInCollectionToNotExistBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[Convert Text To Date Time]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTime.MainDoc" >}} + +[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 Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemWithKey.MainDoc" >}} +[Contains Item With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemWithValue.MainDoc" >}} +[Contains Items With Keys]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemsWithKeys.MainDoc" >}} +[Contains Items With Values]: {{< url path="Cortex.Reference.Blocks.Dictionaries.ContainsItem.ContainsItemsWithValues.MainDoc" >}} +[Get Count Of All Items]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetCount.GetCountOfAllItems.MainDoc" >}} +[Get Count Of Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetCount.GetCountOfItemsWithValue.MainDoc" >}} +[Get Counts Of Items With Values]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetCount.GetCountsOfItemsWithValues.MainDoc" >}} +[Get All Items]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetItem.GetAllItems.MainDoc" >}} +[Get Item With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetItem.GetItemWithKey.MainDoc" >}} +[Get Items With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetItem.GetItemsWithKey.MainDoc" >}} +[Get All Keys]: {{< url path="Cortex.Reference.Blocks.Dictionaries.GetKey.GetAllKeys.MainDoc" >}} +[Remove All Items]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveAllItems.MainDoc" >}} +[Remove Item With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemWithKey.MainDoc" >}} +[Remove Item With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemWithValue.MainDoc" >}} +[Remove Items With Key]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKey.MainDoc" >}} +[Remove Items With Keys]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKeys.MainDoc" >}} +[Remove Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValue.MainDoc" >}} +[Remove Items With Values]: {{< url path="Cortex.Reference.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValues.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 Keys]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithKeys.MainDoc" >}} +[Set Items With Value]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithValue.MainDoc" >}} +[Set Items With Values]: {{< url path="Cortex.Reference.Blocks.Dictionaries.SetItem.SetItemsWithValues.MainDoc" >}} + +[Send Email Using SMTP Server]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.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" >}} +[Rethrow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.RethrowException.RethrowException.MainDoc" >}} + +[Copy File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFile.CopyFile.MainDoc" >}} +[Copy Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFile.CopyFiles.MainDoc" >}} +[Copy Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolder.MainDoc" >}} +[Copy Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.CopyFolders.MainDoc" >}} +[Create Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CreateFolder.CreateFolder.MainDoc" >}} +[Create Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CreateFolder.CreateFolders.MainDoc" >}} +[Delete File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFile.DeleteFile.MainDoc" >}} +[Delete Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFile.DeleteFiles.MainDoc" >}} +[Delete Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFolder.DeleteFolder.MainDoc" >}} +[Delete Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.DeleteFolder.DeleteFolders.MainDoc" >}} +[Duplicate Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.CopyFolder.DuplicateFolder.MainDoc" >}} +[Get File Information]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFileInformation.GetFileInformation.MainDoc" >}} +[Get Folder Content]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFolderContent.GetFolderContent.MainDoc" >}} +[Get Folder Information]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFolderInformation.GetFolderInformation.MainDoc" >}} +[Move File]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFile.MoveFile.MainDoc" >}} +[Move Files]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFile.MoveFiles.MainDoc" >}} +[Move Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolder.MainDoc" >}} +[Move Folders]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.MoveFolder.MoveFolders.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" >}} +[Rename Folder]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.RenameFolder.RenameFolder.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" >}} + +[Convert Json To Object]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertJsonToObject.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" >}} +[Add Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemsAtBeginning.MainDoc" >}} +[Add Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemsAtEnd.MainDoc" >}} +[Add Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemsAtIndex.MainDoc" >}} +[List Contains Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.ContainsItem.ContainsItemWithValue.MainDoc" >}} +[List Contains Items With Values]: {{< url path="Cortex.Reference.Blocks.Lists.ContainsItem.ContainsItemsWithValues.MainDoc" >}} +[List Get Count Of All Items]: {{< url path="Cortex.Reference.Blocks.Lists.GetCount.GetCountOfAllItems.MainDoc" >}} +[List Get Count Of Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.GetCount.GetCountOfItemsWithValue.MainDoc" >}} +[List Get Count Of Items With Values]: {{< url path="Cortex.Reference.Blocks.Lists.GetCount.GetCountOfItemsWithValues.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" >}} +[Get Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtBeginning.MainDoc" >}} +[Get Item At End]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtEnd.MainDoc" >}} +[Get Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtIndex.MainDoc" >}} +[Get Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtBeginning.MainDoc" >}} +[Get Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtEnd.MainDoc" >}} +[Get Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtIndex.MainDoc" >}} +[Get Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtIndexes.MainDoc" >}} +[List Remove All Items]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveAllItems.MainDoc" >}} +[Remove Duplicate Items]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveDuplicateItems.MainDoc" >}} +[Remove Item At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemAtBeginning.MainDoc" >}} +[Remove Item At End]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemAtEnd.MainDoc" >}} +[Remove Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemAtIndex.MainDoc" >}} +[List Remove Item With Value]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemWithValue.MainDoc" >}} +[Remove Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtBeginning.MainDoc" >}} +[Remove Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtEnd.MainDoc" >}} +[Remove Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndex.MainDoc" >}} +[Remove Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndexes.MainDoc" >}} +[List Remove Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsWithValue.MainDoc" >}} +[List Remove Items With Values]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsWithValues.MainDoc" >}} +[List Set All Items]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetAllItems.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" >}} +[Set Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtBeginning.MainDoc" >}} +[Set Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtEnd.MainDoc" >}} +[Set Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndex.MainDoc" >}} +[Set Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndexes.MainDoc" >}} +[List Set Items With Value]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsWithValue.MainDoc" >}} +[List Set Items With Values]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsWithValues.MainDoc" >}} + +[Log Event]: {{< url path="Cortex.Reference.Blocks.Logs.LogEvent.LogEvent.MainDoc" >}} + +[For Loop]: {{< url path="Cortex.Reference.Blocks.Loops.For.ForLoop.MainDoc" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} + +[Dequeue Item]: {{< url path="Cortex.Reference.Blocks.Queues.DequeueItem.DequeueItemBlock.MainDoc" >}} +[Dequeue Items]: {{< url path="Cortex.Reference.Blocks.Queues.DequeueItem.DequeueItemsBlock.MainDoc" >}} +[Enqueue Item]: {{< url path="Cortex.Reference.Blocks.Queues.EnqueueItem.EnqueueItemBlock.MainDoc" >}} +[Enqueue Items]: {{< url path="Cortex.Reference.Blocks.Queues.EnqueueItem.EnqueueItemsBlock.MainDoc" >}} +[Queues Get Count Of All Items]: {{< url path="Cortex.Reference.Blocks.Queues.EnqueueItem.GetCountOfAllItemsBlock.MainDoc" >}} +[Peek Item]: {{< url path="Cortex.Reference.Blocks.Queues.PeekItem.PeekItemBlock.MainDoc" >}} +[Q Remove All Items]: {{< url path="Cortex.Reference.Blocks.Queues.RemoveItem.RemoveAllItemsBlock.MainDoc" >}} + +[Cancel Task]: {{< url path="Cortex.Reference.Blocks.Tasks.CancelTask.CancelTaskBlock.MainDoc" >}} +[Cancel All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.CancelTask.CancelAllTasksBlock.MainDoc" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} + +[Contains All Text]: {{< url path="Cortex.Reference.Blocks.Text.ContainsText.ContainsAllText.MainDoc" >}} +[Contains Any Text]: {{< url path="Cortex.Reference.Blocks.Text.ContainsText.ContainsAnyText.MainDoc" >}} +[Format Text With Values]: {{< url path="Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues.MainDoc" >}} +[Join Text]: {{< url path="Cortex.Reference.Blocks.Text.JoinText.JoinText.MainDoc" >}} + +[Convert Structure To Xml]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertStructureToXml.MainDoc" >}} +[Convert Xml To Structure]: {{< url path="Cortex.Reference.Blocks.Xml.ConvertXml.ConvertXmlToStructure.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" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + + diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-value-out-of-range-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-value-out-of-range-exception.md new file mode 100644 index 000000000..097c5a062 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/Property/property-value-out-of-range-exception.md @@ -0,0 +1,371 @@ +--- +title: "PropertyValueOutOfRangeException" +linkTitle: "PropertyValueOutOfRangeException" +description: "The exception thrown when a property is provided with a value that falls outside its accepted range." +--- + +# {{< param title >}} + +

(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 '' provided. +There are no items in ''. +Check that '' is not empty. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the empty collection [property][]. +* `` is the name of another [property][] used to perform the get, set or remove operation (e.g. `index`, `indexes`, `count` etc.). + +#### How to fix + +Provide a non-empty collection [property][]. + +### Property Is Empty Or `null` + +An operation such as adding, getting or removing text from a `null` or empty (i.e. `""`) text [property][] was performed. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Invalid '' provided. +Check that '' is not null or empty. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the `null` or empty (i.e. `""`) text [property][]. + +#### How to fix + +Provide a non-`null` or non-empty text [property][]. + +### Property Is Invalid + +A [property][] was set to an invalid value. + +#### Message Format + +The format of the [Message][] can be one of the following: + +```json +"'' given was ; it must be a value between and . +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"'' given was ; it must be a value between and (). +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"`` given was ; it must be less than or equal to . +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"'' given was and '' given was . +The '' must be less than or equal to (). +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid '' provided. +The values in '' are outside of the expected range. +Check that the provided values of '' are between and . +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the [property][] with the invalid value (e.g. `Length`, `Count`, `Index`). +* `` is the invalid value of the [property][] (e.g. `100` for non-collection values or `100, 200` for collection values). +* `` is the minimum value allowed (e.g. `0`). +* `` is the maximum value allowed (e.g. `9`). +* `` is how the maximum allowed value is calculated (e.g. `'Text.Length' - 1`). +* `` is the name of a related [property][] relevant to the exception (e.g. `Index`). +* `` is the value of a related [property][] relevant to the exception (e.g. `1`). + +#### How to fix + +Provide a valid value for the [property][] as instructed by the [Message][]. + +### Property Is Negative + +A [property][] was set to a negative [TimePeriod][] when a positive [TimePeriod][] was required. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The provided 'TimePeriod' () equates to milliseconds which is invalid; it must be a non-negative value. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the [TimePeriod][] value in its text representation (e.g. `0.0.0.0:0:0:-10`). +* `` is the [TimePeriod][] value represented as total milliseconds (e.g. `-10`). + +#### How to fix + +Provide a valid non-negative [TimePeriod][] value for the [property][] as instructed by the [Message][]. + +### Property Greater Than Maximum Value + +A positive [TimePeriod][] was added to the [property][] or a negative [TimePeriod][] was subtracted from the [property][], and the result is greater than the allowed maximum value of the [DateTimeOffset][] data type. + +#### Message Format + +The format of the [Message][] can be one of the following: + +* If a positive [TimePeriod][] was added + +```json +"The provided 'DateTimeOffset' () with the addition of the given 'TimePeriod' () is greater than the maximum of a DateTimeOffset (). +Please click the HelpLink for more information on how to fix this." +``` + +* If a negative [TimePeriod][] value was subtracted + +```json +"The provided 'DateTimeOffset' () with the subtraction of the given 'TimePeriod' () is greater than the maximum of a DateTimeOffset (). +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the value of the [DateTimeOffset][] in [ISO 8601 format][] (i.e. `2022-07-01T14:00:00.0000000+01:00`). +* `` is the value of the [TimePeriod][] in text format (i.e. `9999.0.0.0:0:0:0`). +* `` is the maximum value of a [DateTimeOffset][] (i.e. `9999-12-31T23:59:59.9999999+00:00`). + +#### How to fix + +Provide a [TimePeriod][] value that when added to or subtracted from the [property][] results in the [property][] being less than the allowed maximum value of the [DateTimeOffset][] data type. + +### Property Less Than Minimum Value + +A positive [TimePeriod][] was subtracted from the [property][] or a negative [TimePeriod][] was added to the [property][], and the result was less than the allowed minimum value of the [DateTimeOffset][] data type. + +#### Message Format + +The format of the [Message][] can be one of the following: + +* If a positive [TimePeriod][] was subtracted + +```json +"The provided 'DateTimeOffset' () with the subtraction of the given 'TimePeriod' () is less than the minimum of a DateTimeOffset (). +Please click the HelpLink for more information on how to fix this." +``` + +* If a negative [TimePeriod][] value was added + +```json +"The provided 'DateTimeOffset' () with the addition of the given 'TimePeriod' () is less than the minimum of a DateTimeOffset (). +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the value of the [DateTimeOffset][] in [ISO 8601 format][] (i.e. `2022-07-01T14:00:00.0000000+01:00`). +* `` is the value of the [TimePeriod][] in text format (i.e. `-9999.0.0.0:0:0:0`). +* `` is the minimum value of a [DateTimeOffset][] (i.e. `0001-01-01T00:00:00.0000000+00:00`). + +#### How to fix + +Provide a [TimePeriod][] value that when added to or subtracted from the [property][] results in the [property][] being greater than the allowed minimum value of the [DateTimeOffset][] data type. + +## Properties + +### Exception Type + +The type of the exception (i.e. `PropertyValueOutOfRangeException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +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 + +None + +## See Also + +### Related Data Types + +* Date & Time + * [DateTimeOffset][] + * [TimePeriod][] +* Text + * [String][] + +### Related Concepts + +* [Exceptions][] +* [Working with Collections][] +* [Working with Date and Time][] +* [Working with Text][] + +### Related Blocks + +* Date & Time + * [Add Time Period][] + * [Subtract Time Period][] +* Lists + * [Add Item At Index][] + * [Add Items At Index][] + * [Get Item At Index][] + * [Get Items At Beginning][] + * [Get Items At End][] + * [Get Items At Index][] + * [Get Items At Indexes][] + * [Remove Item At Index][] + * [Remove Items At Beginning][] + * [Remove Items At End][] + * [Remove Items At Index][] + * [Remove Items At Indexes][] + * [Set Item At Index][] + * [Set Items At Index][] + * [Set Items At Indexes][] +* PowerShell + * [Execute PowerShell Script][] +* Queues + * [Dequeue Items][] +* Schedules + * [Wait For Duration][] +* Text + * [Add Text After Index][] + * [Add Text Before Index][] + * [Get Text At Beginning][] + * [Get Text At End][] + * [Get Text At Index][] + * [Get Text Before Index][] + * [Get Text Between Indexes][] + * [Remove Text At Beginning][] + * [Remove Text At End][] + * [Remove Text At Index][] + * [Remove Text Before Index][] + * [Remove Text Between Indexes][] + +### External Documentation + +None + +[Property Greater Than Maximum Value]: {{< ref "#property-greater-than-maximum-value" >}} +[Property Less Than Minimum Value]: {{< ref "#property-less-than-minimum-value" >}} +[Property Is Empty]: {{< ref "#property-is-empty" >}} +[Property Is Empty Or `null`]: {{< ref "#property-is-empty-or-null" >}} +[Property Is Invalid]: {{< ref "#property-is-invalid" >}} +[Property Is Negative]: {{< ref "#property-is-negative" >}} + +[Message]: {{< ref "#message" >}} + +[Add Time Period]: {{< url path="Cortex.Reference.Blocks.DateAndTime.AddTimePeriod.AddTimePeriod.MainDoc" >}} +[Subtract Time Period]: {{< url path="Cortex.Reference.Blocks.DateAndTime.SubtractTimePeriod.SubtractTimePeriod.MainDoc" >}} + +[Add Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemAtIndex.MainDoc" >}} +[Add Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.AddItem.AddItemsAtIndex.MainDoc" >}} +[Get Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemAtIndex.MainDoc" >}} +[Get Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtBeginning.MainDoc" >}} +[Get Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtEnd.MainDoc" >}} +[Get Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtIndex.MainDoc" >}} +[Get Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.GetItem.GetItemsAtIndexes.MainDoc" >}} +[Remove Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemAtIndex.MainDoc" >}} +[Remove Items At Beginning]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtBeginning.MainDoc" >}} +[Remove Items At End]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtEnd.MainDoc" >}} +[Remove Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndex.MainDoc" >}} +[Remove Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.RemoveItem.RemoveItemsAtIndexes.MainDoc" >}} +[Set Item At Index]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemAtIndex.MainDoc" >}} +[Set Items At Index]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndex.MainDoc" >}} +[Set Items At Indexes]: {{< url path="Cortex.Reference.Blocks.Lists.SetItem.SetItemsAtIndexes.MainDoc" >}} + +[Execute PowerShell Script]: {{< url path="Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript.MainDoc" >}} + +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} + +[Add Text After Index]: {{< url path="Cortex.Reference.Blocks.Text.AddText.AddTextAfterIndex.MainDoc" >}} +[Add Text Before Index]: {{< url path="Cortex.Reference.Blocks.Text.AddText.AddTextBeforeIndex.MainDoc" >}} +[Get Text At Beginning]: {{< url path="Cortex.Reference.Blocks.Text.GetText.GetTextAtBeginning.MainDoc" >}} +[Get Text At End]: {{< url path="Cortex.Reference.Blocks.Text.GetText.GetTextAtEnd.MainDoc" >}} +[Get Text At Index]: {{< url path="Cortex.Reference.Blocks.Text.GetText.GetTextAtIndex.MainDoc" >}} +[Get Text Before Index]: {{< url path="Cortex.Reference.Blocks.Text.GetText.GetTextBeforeIndex.MainDoc" >}} +[Get Text Between Indexes]: {{< url path="Cortex.Reference.Blocks.Text.GetText.GetTextBetweenIndexes.MainDoc" >}} +[Remove Text At Beginning]: {{< url path="Cortex.Reference.Blocks.Text.RemoveText.RemoveTextAtBeginning.MainDoc" >}} +[Remove Text At End]: {{< url path="Cortex.Reference.Blocks.Text.RemoveText.RemoveTextAtEnd.MainDoc" >}} +[Remove Text At Index]: {{< url path="Cortex.Reference.Blocks.Text.RemoveText.RemoveTextAtIndex.MainDoc" >}} +[Remove Text Before Index]: {{< url path="Cortex.Reference.Blocks.Text.RemoveText.RemoveTextBeforeIndex.MainDoc" >}} +[Remove Text Between Indexes]: {{< url path="Cortex.Reference.Blocks.Text.RemoveText.RemoveTextBetweenIndexes.MainDoc" >}} + +[property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} +[ISO 8601 format]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} + +[Dequeue Items]: {{< url path="Cortex.Reference.Blocks.Queues.DequeueItem.DequeueItemsBlock.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/Common/_index.md b/content/en/docs/2024.9/Reference/Exceptions/Common/_index.md new file mode 100644 index 000000000..3aa58c5d8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Common/_index.md @@ -0,0 +1,5 @@ +--- +title: "Common" +linkTitle: "Common" +description: "Exceptions related to commonly occurring errors" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/Lists/_index.md b/content/en/docs/2024.9/Reference/Exceptions/Lists/_index.md new file mode 100644 index 000000000..a0ad39d72 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Lists/_index.md @@ -0,0 +1,5 @@ +--- +title: "List" +linkTitle: "Lists" +description: "Exceptions related to Lists" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/Lists/cannot-modify-read-only-list-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Lists/cannot-modify-read-only-list-exception.md new file mode 100644 index 000000000..58f7c331f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Lists/cannot-modify-read-only-list-exception.md @@ -0,0 +1,72 @@ +--- +title: "CannotModifyReadOnlyListException" +linkTitle: "CannotModifyReadOnlyListException" +description: "The exception thrown when trying to modify a read-only list." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Lists.CannotModifyReadOnlyListException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when trying to modify a read-only list. + +> Lists implementing [IList][]<[TItem][]> have the option to be read-only (e.g. [IReadOnlyList][]<[TItem][]>). + +## Reasons + +### Attempting to modify a read-only list + +The execution is attempting to perform a non-read operation on a read-only [IList][]<[TItem][]>. + +##### Message Format + +There was an attempt to modify a read-only list. + +##### Message Format + +The format of the exception message is as follows: + +```json +"'' cannot be modified because it's read-only. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the read-only list. + +#### How to fix + +If the list was written directly into the block property using an [expression][], use a list type that is not read-only, such as [List][]<[TItem][]>. + +When using a variable, convert the read-only list to a list that can be written to by using the `.ToList()` expression like follows: + +```CSharp +($)List.ToList() +``` + +## Remarks + +### Known Limitations + +None + +## See Also + +#### External Documentation + +* [System.Collections.Generic.IList<T>][MS IList] +* [System.Collections.Generic.List<T>][MS List] + +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.Expressions" >}} + +[List]: {{}} +[IList]: {{}} +[IReadOnlyList]: {{}} + +[MS List]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.List" >}} +[MS IList]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IList" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/Lists/duplicate-value-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Lists/duplicate-value-exception.md new file mode 100644 index 000000000..e5b81f1aa --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Lists/duplicate-value-exception.md @@ -0,0 +1,54 @@ +--- +title: "DuplicateValueException" +linkTitle: "DuplicateValueException" +description: "The exception thrown when a list has duplicate values but shouldn't." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Lists.DuplicateValueException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a [list][IList] has duplicate values but shouldn't. + +## Reasons + +### Duplicate values in list when not supported + +A [list][IList] provided for an operation requiring unique values contains at least one duplicate value (e.g. providing duplicate indexes for the `Indexes` property of the [Get Items At Indexes][] block). + +#### Message Format + +The format of the exception message is as follows: + +```json +"The value of '' cannot contain duplicate values. +The values in '' are duplicated. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the list that has duplicate values. +* `` is the list of values that are duplicated in the list. + +#### How to fix + +Ensure that duplicate values do not exist within the list being provided. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[IList]: {{}} +[Get Items At Indexes]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/Xml/_index.md b/content/en/docs/2024.9/Reference/Exceptions/Xml/_index.md new file mode 100644 index 000000000..0b563947c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Xml/_index.md @@ -0,0 +1,5 @@ +--- +title: "Xml" +linkTitle: "Xml" +description: "Exceptions related to Xml" +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/Xml/xml-serialization-exception.md b/content/en/docs/2024.9/Reference/Exceptions/Xml/xml-serialization-exception.md new file mode 100644 index 000000000..bab1052dc --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/Xml/xml-serialization-exception.md @@ -0,0 +1,113 @@ +--- +title: "XmlSerializationException" +linkTitle: "XmlSerializationException" +description: "The exception thrown when an error occurs when serializing or deserializing XML." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Xml.XmlSerializationException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an error occurs when serializing or deserializing XML. + +## Reasons + +### Invalid Structure {#structure} + +The [Structure][ConvertStructureToXml Structure Property] provided to the [Convert Structure To Xml][ConvertStructureToXml] block is invalid. + +#### Message Format + +The format of the message can be one of the following: + +```json +"Invalid 'Structure' provided. The 'Structure' has been provided an empty key that could not be converted to valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Structure' provided. The 'Structure' has been provided a key that could not be converted to valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Structure' provided. The 'Structure' has been provided an xml declaration key with an attribute value that could not be converted to valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Structure' provided. The 'Structure' has been provided a document type definition key with an attribute value that could not be converted to valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Structure' provided. The 'Structure' has been provided an attribute key with a value that could not be converted to valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +* Ensure that all keys in the structure provided are not empty (i.e. `""`). The path to the specific key which threw this exception can be seen in the `Key` property (e.g. `"firstItem."` indicates that the empty key is a child of a top level item that has the key `"firstItem"`). If a top level item has an empty key (i.e. `""`), then the `Key` property will also be empty (i.e. `""`). +* Ensure that the XML declaration key (i.e. `"?xml"`) and document type definition key (i.e. `"!DOCTYPE"`) in the structure provided only have valid attributes: + * XML declaration key: `"@version"`, `"@encoding"` and `"@standalone"` + * Document type definition key: `"@name"`, `"@public"`, `"@system"` and `"@internalSubset"` + + The path to the specific key which threw this exception can be seen in the `Key` property. +* Ensure that all child attribute keys of the XML declaration item, in the structure provided, have values with a valid [Basic Data Type][BasicDataTypes] (e.g. the child attribute key `"@version"`, requires a numeric value like `1.0` or `1.1`, so a value of `false` is invalid). +* Ensure that all child attribute keys of the document type definition item, in the structure provided, have values with a valid [Basic Data Type][BasicDataTypes] (e.g. the child attribute key `"@name"`, requires a text value like `"exampleName"`, so a value of `22` is invalid). +* Ensure that all attribute keys in the structure provided have values which are not a [Complex Data Type][ComplexDataTypes]. The path to the specific key which threw this exception can be seen in the `Key` property. + +### Invalid XML {#xml} + +The [XML][ConvertXmlToStructure XML Property] provided to the [Convert Xml to Structure][ConvertXmlToStructure] block is invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid 'Xml' provided. The 'Xml' provided is not valid xml. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure that the [XML][ConvertXmlToStructure XML Property] provided is [valid XML][XmlValidator]. See the `Message` of the `InnerException` property for more information. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [XML Validator][XmlValidator] + +[Structure]: {{}} + +[ConvertStructureToXml]: {{}} +[ConvertStructureToXml Structure Property]: {{}} + +[ConvertXmlToStructure]: {{}} +[ConvertXmlToStructure XML Property]: {{}} + +[XmlNodes]: {{}} + +[BasicDataTypes]: {{}} +[ComplexDataTypes]: {{}} + +[XmlValidator]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/_index.md b/content/en/docs/2024.9/Reference/Exceptions/_index.md new file mode 100644 index 000000000..a86fc4ede --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/collections/_index.md b/content/en/docs/2024.9/Reference/Exceptions/collections/_index.md new file mode 100644 index 000000000..274cfc43a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/collections/occurrence-not-present-exception.md b/content/en/docs/2024.9/Reference/Exceptions/collections/occurrence-not-present-exception.md new file mode 100644 index 000000000..be890e4fa --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/collections/occurrence-not-present-exception.md @@ -0,0 +1,111 @@ +--- +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)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## 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. + +## Reasons + +### Occurrence provided is zero + +The occurrence provided is equal to `0`. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +" 0 cannot be used as it will perform no operations. +Please use a value greater or less than 0. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property which is not present. + +#### How to fix + +Provide an occurrence which is non-zero. + +### Positive occurrence not present + +The nth occurrence is not present. + +#### Message Format + +The format of the message is as follows: + +```json +"The occurrence of the key is not present in '' +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the specific occurrence that could not be found (e.g. 1st, 2nd, 3rd) +* `` is the value of the key that was searched for in the collection +* `` is the name of the collection in which the search for the key took place. + +#### How to fix + +Provide an occurrence which is present (e.g. if there are 3 occurrences, you must specify a value between 1 and 3). + +### Negative occurrence not present + +The nth from last occurrence is not present. + +#### Message Format + +The format of the message is as follows: + +```json +"The from last occurrence of the key is not present in '' +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the specific occurrence that could not be found (e.g. 1st, 2nd, 3rd) +* `` is the value of the key that was searched for in the collection +* `` is the name of the collection in which the search for the key took place. + +#### How to fix + +Provide an occurrence from last which is present (e.g. if there are 3 occurrences, you must specify a value between -1 and -3). + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[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" >}} +[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/2024.9/Reference/Exceptions/concurrency/_index.md b/content/en/docs/2024.9/Reference/Exceptions/concurrency/_index.md new file mode 100644 index 000000000..664797ba5 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/concurrency/semaphores/_index.md b/content/en/docs/2024.9/Reference/Exceptions/concurrency/semaphores/_index.md new file mode 100644 index 000000000..5d379dfd2 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md b/content/en/docs/2024.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md new file mode 100644 index 000000000..213525541 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/concurrency/semaphores/semaphore-could-not-be-acquired-exception.md @@ -0,0 +1,195 @@ +--- +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 '///*//*//' could not be acquired. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the tenant defined in the [Scope][] the semaphore operates in. +* `` is the system defined in the [Scope][] the semaphore operates in. +* `` is the package defined in the [Scope][] the semaphore operates in. +* `` is the flow defined in the [Scope][] the semaphore operates in. +* `` is the [Name][SemaphoreName] of the semaphore. + +#### How to fix + +Try to acquire the semaphore again or provide a queue in the [Queue][SemaphoreQueue]. + +### Queue Timeout reached + +When queueing for the specified semaphore, the [Queue Timeout] is reached before the semaphore is acquired. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Requested semaphore '///*//*//' could not be acquired. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the tenant defined in the [Scope][] the semaphore operates in. +* `` is the system defined in the [Scope][] the semaphore operates in. +* `` is the package defined in the [Scope][] the semaphore operates in. +* `` is the flow defined in the [Scope][] the semaphore operates in. +* `` is the [Name][SemaphoreName] of the semaphore. + +#### How to fix + +Try to acquire the semaphore again or provide a longer [Queue Timeout]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `SemaphoreCouldNotBeAcquiredException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Scope + +The [Scope] the semaphore operates in. + +| | | +|-----------|------------| +| Data Type | [Scope][SemaphoreScope] | + +### Semaphore Name + +The [Name][SemaphoreName] of the semaphore that was attempted to be acquired. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Configured Concurrency Limit + +The number of executions allowed in the semaphore that was attempted to be acquired. + +This is the concurrency limit set when the semaphore was created, which may be different from the specified concurrency limit, see [Multiple Concurrency Limits][MultipleConcurrencyLimits] for more information. + +| | | +|-----------|-----------| +| Data Type | [Int32][] | + +### Queued + +Whether or not the execution attempted to queue. + +| | | +|-----------|-------------| +| Data Type | [Boolean][] | + +### Queue Timeout + +The length of time the execution queued. + +| | | +|-----------|----------------| +| Data Type | [TimePeriod][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## See Also + +### Related Data Types + +* [Boolean][] +* [Int32][] +* [Scope][SemaphoreScope] +* [String][] +* [TimePeriod][] + +### Related Concepts + +* [Exceptions][] +* [Scopes][] +* [Semaphores][Semaphore] + +### Related Blocks + +* [All Blocks][] + +Except: + +* [End Flow][] +* [End Workspace][] +* [Handle Flow Exception][] +* [Start Flow][] +* [Wait For Duration][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} +[Scope]: {{< ref "#scope" >}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} +[Semaphore]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.MainDoc" >}} +[SemaphoreWhatIs]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MainDoc" >}} + +[SemaphoreConcurrencyLimit]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.ConcurrencyLimit" >}} +[SemaphoreQueue]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Queue" >}} +[Scopes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Scopes.MainDoc" >}} +[SemaphoreScope]: {{< url path="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc" >}} +[SemaphoreName]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.Name" >}} +[Queue Timeout]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.QueueTimeout" >}} + +[MultipleConcurrencyLimits]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MultipleConcurrencyLimits" >}} + +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/data-storage/_index.md b/content/en/docs/2024.9/Reference/Exceptions/data-storage/_index.md new file mode 100644 index 000000000..d56b1cc12 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data-storage/_index.md @@ -0,0 +1,5 @@ +--- +title: "Data Storage" +linkTitle: "Data Storage" +description: "Exceptions related to Data Storage" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/data-storage/data-storage-collection-not-found-exception.md b/content/en/docs/2024.9/Reference/Exceptions/data-storage/data-storage-collection-not-found-exception.md new file mode 100644 index 000000000..592c89a63 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data-storage/data-storage-collection-not-found-exception.md @@ -0,0 +1,121 @@ +--- +title: "DataStorageCollectionNotFoundException" +linkTitle: "DataStorageCollectionNotFoundException" +description: "The exception thrown when a data storage collection could not be found." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.DataStorage.DataStorageCollectionNotFoundException)

+ +## Description + +The exception thrown when an operation attempts to retrieve a [Data Storage Collection][] that does not exist in the [Scope][] specified by the [ScopeDefinition][]. + +## Reasons + +### Data Storage Collection Could Not Be Found + +The [Data Storage Collection][] could not be found in the [Scope][] specified by the [ScopeDefinition][]. + +#### Message Format + +```json +"The '' collection was not found. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` will be the name of the collection that could not be found (e.g. `"users"`). + +#### How to fix + +Ensure the provided [Data Storage Collection][] exists. A [Data Storage Collection][] can be created using the [Create Collection][] block. + +## Properties + +### Exception Type + +The type of the exception (i.e. `DataStorageCollectionNotFoundException`) + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: +- `` will be replaced with the name of the collection. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Scope + +The scope of the collection specified. + +| | | +|-----------|---------------------------| +| Data Type | [Scope][] | + +### CollectionName + +The name of the collection that could not be found within the [Scope][] specified by the [ScopeDefinition][] provided. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### 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 + +* [Scope][] +* [ScopeDefinition][] +* [String][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +- Data Storage + - [Delete Data With Key][] + - [Read Data With Key][] + - [Write Data With Key][] + +### External Documentation + +None + +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} +[Delete Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.MainDoc">}} +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Scope]: {{< url path="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/data-storage/key-in-data-storage-collection-not-found-exception.md b/content/en/docs/2024.9/Reference/Exceptions/data-storage/key-in-data-storage-collection-not-found-exception.md new file mode 100644 index 000000000..4bb532f9e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data-storage/key-in-data-storage-collection-not-found-exception.md @@ -0,0 +1,129 @@ +--- +title: "KeyInDataStorageCollectionNotFoundException" +linkTitle: "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." +--- + +# {{% param title %}} + +

(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 is not present in '', so cannot be retrieved. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` will be the name of the key that could not be found (e.g. `"user1"`) +- `` will be the name of the collection that the key could not be found in (e.g. `"users"`). + +#### How to fix + +Ensure the provided key exists. Keys can be added to the [Data Storage Collection][] using the [Write Data With Key][] block. + +## Properties + +### Exception Type + +The type of the exception (i.e. `KeyInDataStorageCollectionNotFoundException`) + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: + +- `` will be replaced with the specified key. +- `` will be replaced with the name of the collection. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Scope + +The scope of the collection specified. + +| | | +|-----------|---------------------------| +| Data Type | [Scope][] | + +### CollectionName + +The name of the collection the [Key][Key Property] was attempted to retrieve from. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### Key + +The key that could not be found in the [Data Storage Collection][]. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### 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 + +* [Scope][] +* [ScopeDefinition][] +* [String][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +- Data Storage + - [Read Data With Key][] + +### External Documentation + +None + +[Key Property]: {{< ref "#key">}} + +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Scope]: {{< url path="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} +[ScopeDefinition]: {{< url path="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[Data Storage Collection]: {{< url path = "Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.DataStorage">}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/data/_index.md b/content/en/docs/2024.9/Reference/Exceptions/data/_index.md new file mode 100644 index 000000000..0648e7fde --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data/_index.md @@ -0,0 +1,5 @@ +--- +title: "Data" +linkTitle: "Data" +description: "Exceptions related to Data Sources" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/data/command-exception.md b/content/en/docs/2024.9/Reference/Exceptions/data/command-exception.md new file mode 100644 index 000000000..505d331eb --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data/command-exception.md @@ -0,0 +1,347 @@ +--- +title: "CommandException" +linkTitle: "CommandException" +description: "The exception thrown when any command execution has resulted in an exception being thrown." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Data.CommandException)

+ +## Description + +The exception thrown when any command execution has resulted in an exception being thrown. + +## Reasons + +### Connection Failed {#1000} + +An [Error Code][] of `1000` indicates the connection to the data source failed. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"Failed to open the '' connection. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the type of the data source (e.g. SqlServer, Oracle). + +#### How to fix + +Make sure that the [Connection Details Property][ConnectionDetailsProperty] has been given a valid connection string, and that the data source is active. + +More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the [InnerException][]. + +### Statement {#2000} + +An [Error Code][] of `2000` indicates the statement(s) used could not be parsed. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"An error occurred whilst trying to execute the command provided. Please see the 'StatementExceptions' property for more details. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Make sure that the statement(s) inputted into the [Command Property][CommandProperty] have the correct syntax. + +More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the [StatementExceptions][]. + +### Incompatible Statement Type (Oracle Only) {#2001} + +An [Error Code][] of `2001` indicates an [OracleBlockStatement][] has been used in the [Command Property][CommandProperty] when using a [Command][] or [Commands][] data type. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'CommandText' contains a block statement; it must be provided with a non-block statement. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Use a [QueryCommand][] or [NonQueryCommand][] data type. + +### Multiple Statements {#2002} + +An [Error Code][] of `2002` indicates multiple statements have been passed into the [Command Property][CommandProperty] when using a [Command][] data type. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'CommandText' contains multiple statements; it must be provided with a single statement. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Use a [Commands][] data type. + +### Incompatible Parameter Type {#2003} + +An [Error Code][] of `2003` indicates an incompatible parameter type has been passed into the [Parameters Property][ParametersProperty] when using a type of [ConnectionDetails][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"'Parameters' contains parameter(s) of a type that is not compatible with the ConnectionDetails used; it must be provided with compatible parameter(s).\r\nPlease click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Use a compatible parameter data type for the type of [ConnectionDetails][] used. + +- [SqlServerConnectionDetails][] compatible types: + + * [Structure][] + +- [OdbcConnectionDetails][] compatible types: + + * [Structure][] + +- [OracleConnectionDetails][] compatible types: + + * [Structure][] + * [OracleParameters][] + * [OracleParameter][] + * [IEnumberable][]<[OracleParameter][]> + +### Runtime {#3000} + +An [Error Code][] of `3000` indicates an error has occurred during either parsing or execution of the statement(s). + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"An error occurred whilst trying to execute the command provided. Please see the 'StatementExceptions' property for more details. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Try to make sure that the statement(s) are valid. + +More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the [StatementExceptions][]. + +### Invalid Parameter Binding {#3001} + +An [Error Code][] of `3001` indicates at least one parameter has not been defined in the [Parameters Property][ParametersProperty] but has in the [Command Property][CommandProperty], or is not bound correctly; this means that the parameter type and value are not compatible, e.g. declaring a parameter with the type as `OracleMappingType.Blob`, but providing a `OracleMappingType.Int32` value of `1`. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"An error occurred whilst trying to execute the command provided. Please see the 'StatementExceptions' property for more details. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Make sure that all parameters used in the [Command Property][CommandProperty] are defined in the [Parameters Property][ParametersProperty] and have a value that is compatible with the parameter type, e.g. declaring a parameter with the type as `OracleMappingType.Int32`, requires an `OracleMappingType.Int32` value to be provided, for example `1`. + +More information may be present in the [StatementExceptions][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `CommandException`). + +| | | +|-----------|------------| +| 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 based on the type of data source used. + +For `CommandException` there are the following categories: + +- `ODBC` +- `Oracle` +- `SQL` + +| | | +|-----------|------------| +| 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 `CommandException` there are the following error codes: + +- [1000][Connection] - indicates that a [Connection][] error has occurred during the connection process (All Categories) +- [2000][Statement] - indicates that a [Statement][] error has occurred during the parsing process (Oracle Category Only) +- [2001][IncompatibleStatementType] - indicates that a [IncompatibleStatementType][] error has occured due to an [OracleBlockStatement][] being used in the [Command Property][CommandProperty] when using a [Command][] or [Commands][] data type (Oracle Category Only) +- [2002][MultipleStatements] - indicates that a [MultipleStatements][] error has occured because multiple statements have been inputted into the [Command Property][CommandProperty] when using the [Command][] datatype (All Categories) +- [2003][IncompatibleParameterType] - An incompatible parameter type has been passed into the [Parameters property][ParametersProperty] when using a type of [ConnectionDetails][] (All Categories) +- [3000][Runtime] - indicates that a [Runtime][] error has occurred during the runtime process (All Categories) +- [3001][InvalidParameterBinding] - indicates at least one parameter has not been defined in the [Parameters Property][ParametersProperty] but has in the [Command Property][CommandProperty], or is not bound correctly (All Categories) + +| | | +|-----------|---------------------------| +| Data Type | [DataCommandErrorCode][] | + +### InnerException + +An optional property that may contain the exception that caused the current exception. + +| | | +|-----------|---------------| +| Data Type | [Exception][] | + +### StatementExceptions + +An optional property that may contain a list of exception(s) relating to the execution of one or more of the statements specified in the [Command Property][CommandProperty]. + +| | | +|-----------|---------------| +| Data Type | [List][]<[Exception][]> | + +### 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 + +- [Command][] +- [Commands][] +- [ConnectionDetails][] +- [DataCommandErrorCode][] +- [Exception][] +- [NonQueryCommand][] +- [OdbcConnectionDetails][] +- [OracleConnectionDetails][] +- [OracleParameter][] +- [OracleParameters][] +- [QueryCommand][] +- [SqlServerConnectionDetails][] +- [String][] + +### Related Concepts + +- [Exceptions][] +- [Working With Data Sources][] + +### Related Blocks + +- Data + - [Execute Data Command][] + +### External Documentation + +- [OracleBlockStatement][] + +[Connection]: {{< ref "#1000">}} +[Statement]: {{< ref "#2000">}} +[IncompatibleStatementType]: {{< ref "#2001">}} +[MultipleStatements]: {{< ref "#2002">}} +[IncompatibleParameterType]: {{< ref "#2003">}} +[Runtime]: {{< ref "#3000">}} +[InvalidParameterBinding]: {{< ref "#3001">}} +[Message]: {{< ref "#message" >}} +[InnerException]: {{< ref "#innerexception" >}} +[StatementExceptions]: {{< ref "#statementexceptions" >}} +[Error Code]: {{< ref "#error-code" >}} + +[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" >}} +[PropertyEmptyException]: {{< url path="Cortex.Reference.Exceptions.Common.Property.PropertyEmptyException.MainDoc" >}} +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[InvalidConnectionStringException]: {{< url path="Cortex.Reference.Exceptions.Data.InvalidConnectionStringException.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} + +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} +[DataCommandErrorCode]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommandErrorCode.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} + +[Execute Data Command]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.MainDoc" >}} + +[TConnectionDetails]: {{< 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" >}} +[Array]: {{< url path="Cortex.Reference.DataTypes.Collections.Array.MainDoc" >}} +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} + +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[ConnectionDetailsProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ConnectionDetailsProperty" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[DataCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.CommandText" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} + +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Command.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Command.CommandText" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[Commands.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.CommandText" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[QueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.CommandText" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[NonQueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.CommandText" >}} + +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Variable Editor]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.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" >}} +[String Interpolation]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.ConvertingObjectsToText.StringInterpolation" >}} +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} +[Connection String Formats]: {{< url path="ConnectionStrings.MainDoc" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Object Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} + +[IEnumberable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} +[OracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.MainDoc" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/data/invalid-connection-string-exception.md b/content/en/docs/2024.9/Reference/Exceptions/data/invalid-connection-string-exception.md new file mode 100644 index 000000000..ec369dbb8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/data/invalid-connection-string-exception.md @@ -0,0 +1,68 @@ +--- +title: "InvalidConnectionStringException" +linkTitle: "InvalidConnectionStringException" +description: "The exception thrown when an invalid connection string is used." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Data.InvalidConnectionStringException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an invalid connection string is used. + +## Reasons + +### Invalid connection string has been supplied + +The connection string provided was invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"The connection string was invalid and failed with error message: . +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the message of the inner exception caused by the invalid connection string being used. + +#### How to fix + +Ensure that a valid connection string is provided for the data source being connected to; see [connectionstrings.com][ConnectionStrings] for valid examples. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [connectionstrings.com][ConnectionStrings] + +[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" >}} + +[ConnectionStrings]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/decisions/_index.md b/content/en/docs/2024.9/Reference/Exceptions/decisions/_index.md new file mode 100644 index 000000000..194a2d699 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/decisions/property-not-nullable-exception.md b/content/en/docs/2024.9/Reference/Exceptions/decisions/property-not-nullable-exception.md new file mode 100644 index 000000000..5d6c262ed --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/decisions/property-not-nullable-exception.md @@ -0,0 +1,71 @@ +--- +title: "PropertyNotNullableException" +linkTitle: "PropertyNotNullableException" +description: "The exception thrown when a property that requires a nullable value is given a non-nullable value." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Decisions.PropertyNotNullableException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a property that requires a [nullable][Nullable] value is given a non-nullable value. + +## Reasons + +### Invalid data type for property provided + +The data type provided for the property is one that does not allow null values, e.g. [Int32][], [Boolean][], [Char][], etc. + +#### Message Format + +The format of the message is as follows: + +```json +"'' cannot accept data types that do not allow null values (e.g. Int32, Boolean, Char, etc.); it must be provided a data type which allows null values. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property which must have a [nullable][Nullable] type. + +#### How to fix + +Ensure that the type of the value provided to the affected property is one that is [nullable][Nullable]. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Block Timeout]: {{}} +[Executions]: {{}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Flows]: {{}} +[Workspaces]: {{}} + +[Boolean]: {{}} +[Char]: {{}} +[Guid]: {{}} +[Int32]: {{}} +[String]: {{}} + +[Nullable]: {{}} +[WhatIsABlock]: {{}} +[WhatIsAnExecution]: {{}} +[WhatIsAFlow]: {{}} +[WhatIsAWorkspace]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/dictionaries/_index.md b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/_index.md new file mode 100644 index 000000000..603d2052d --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md new file mode 100644 index 000000000..865a46061 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/cannot-modify-read-only-dictionary-exception.md @@ -0,0 +1,67 @@ +--- +title: "CannotModifyReadOnlyDictionaryException" +linkTitle: "CannotModifyReadOnlyDictionaryException" +description: "The exception thrown when trying to modify a read-only dictionary." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when trying to modify a read-only dictionary. + +> Dictionaries implementing [IDictionary][]<[TKey][], [TItem][]> have the option to be read-only. + +## Reasons + +### Attempting to modify a read-only dictionary + +The execution is attempting to perform a non-read operation on a read-only [IDictionary][]<[TKey][], [TItem][]>. + +#### Message Format + +The format of the exception message is as follows: + +```json +"'' cannot be modified because it's read-only. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the read-only dictionary. + +#### How to fix + +If the dictionary was written directly into the block property using an [expression][], use a dictionary type that is not read-only, such as [Dictionary][]<[TKey][], [TItem]>. + +When using a variable, convert the read-only dictionary to a dictionary that can be written to by using the `.ToDictionary(item => item.Key, item => item.Value)` expression like follows: + +```CSharp +($)Dictionary.ToDictionary(item => item.Key, item => item.Value); +``` + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [System.Collections.Generic.Dictionary][MS Dictionary] +* [System.Collections.Generic.IDictionary][MS IDictionary] + +[Dictionary]: {{}} +[IDictionary]: {{}} +[TKey]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[TItem]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} +[expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.Expressions" >}} + +[MS Dictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.Dictionary" >}} +[MS IDictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IDictionary" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-not-present-exception.md b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-not-present-exception.md new file mode 100644 index 000000000..3b3e2d715 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-not-present-exception.md @@ -0,0 +1,81 @@ +--- +title: "KeyNotPresentException" +linkTitle: "KeyNotPresentException" +description: "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." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Dictionaries.KeyNotPresentException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when trying to get an item from a [dictionary][IDictionary], or set an item in a [dictionary][IDictionary], with a key that is not present. + +## Reasons + +### Dictionary is empty + +The [dictionary][IDictionary] being accessed is empty, i.e. it contains no items. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The key is not present in '', so cannot be retrieved because '' is empty. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the key that is not present. +* `` is the name of the property containing the empty [dictionary][IDictionary] that is being accessed. + +#### How to fix + +Ensure that the dictionary is not empty, and has the key that is being used. + +### Key not present in dictionary + +The key being used does not exist as a key in the [dictionary][IDictionary] being accessed. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The key is not present in '', so cannot be retrieved. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the key that is not present. +* `` is the name of the property containing the [dictionary][IDictionary] that is being accessed. + +#### How to fix + +Ensure that the key is correct and is present in the [dictionary][IDictionary], for example by using the [Contains Item With Key][Contains Item With Key Block] block. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [System.Collection.Generics.Dictionary][MS Dictionary] +* [System.Collection.Generics.IDictionary][MS IDictionary] + +[Contains Item With Key Block]: {{}} + +[Dictionary]: {{}} +[IDictionary]: {{}} + +[MS Dictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.Dictionary" >}} +[MS IDictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IDictionary" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-present-exception.md b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-present-exception.md new file mode 100644 index 000000000..a9727d10d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/key-present-exception.md @@ -0,0 +1,59 @@ +--- +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)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when trying to add an item to a [dictionary][IDictionary] with a key that is already present. + +## Reasons + +### Key is already present in dictionary + +The key being used to add an item to a [dictionary][IDictionary] already exists within the [dictionary][IDictionary]. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The key is already present in '', so cannot be added. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the key being used to add an item. +* `` is the name of the property containing the [dictionary][IDictionary] to which the item is trying to be added. + +#### How to fix + +Ensure that the key is not a duplicate of an already existing key in the [dictionary][IDictionary], for example by using the [Contains Item With Key][Contains Item With Key Block] block. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [System.Collections.Generic.Dictionary][MS Dictionary] +* [System.Collections.Generic.IDictionary][MS IDictionary] + +[Contains Item With Key Block]: {{}} + +[Dictionary]: {{}} +[IDictionary]: {{}} + +[MS Dictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.Dictionary" >}} +[MS IDictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IDictionary" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md new file mode 100644 index 000000000..8c6079678 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/dictionaries/keys-not-present-exception.md @@ -0,0 +1,83 @@ +--- +title: "KeysNotPresentException" +linkTitle: "KeysNotPresentException" +description: "The exception thrown when trying to get items from a dictionary, or set items in a dictionary, and one or more of the keys used to find the items is not present." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Dictionaries.KeysNotPresentException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when trying to get items from a [dictionary][IDictionary], or set items in a [dictionary][IDictionary], and one or more of the keys used to find the items is not present. + +## Reasons + +### Dictionary is empty + +The [dictionary][IDictionary] being accessed is empty. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The following keys are not present in '', so cannot be retrieved because '' is empty. + +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing [dictionary][IDictionary] being accessed. +* `` is the list of keys that were not present in the [dictionary][IDictionary]. In this case it should be all keys provided. + +#### How to fix + +Ensure that the [dictionary][IDictionary] is not empty. + +### One or more keys not present + +Some of the keys provided were not present in the [dictionary][IDictionary]. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The following keys are not present in '', so cannot be retrieved. + +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing [dictionary][IDictionary] being accessed. +* `` is the list of keys that were not present in the [dictionary][IDictionary]. + +#### How to fix + +Ensure that the [dictionary][IDictionary] contains the key, for example by using the [Contains Item With Key][Contains Item With Key Block] block. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [System.Collections.Generic.Dictionary][MS Dictionary] +* [System.Collections.Generic.IDictionary][MS IDictionary] + +[Contains Item With Key Block]: {{}} + +[Dictionary]: {{}} +[IDictionary]: {{}} + +[MS Dictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.Dictionary" >}} +[MS IDictionary]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IDictionary" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/email/_index.md b/content/en/docs/2024.9/Reference/Exceptions/email/_index.md new file mode 100644 index 000000000..02bf88c2a --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/email/email-session-exception.md b/content/en/docs/2024.9/Reference/Exceptions/email/email-session-exception.md new file mode 100644 index 000000000..90b9c6a76 --- /dev/null +++ b/content/en/docs/2024.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' ('') on 'Port' () failed. The 'Server Details' in 'Email Session Details' has been provided a port that does not exist or the connection timed out. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the address of the mail server that a session is being opened with +- `` is the port on the mail server that a session is being opened with + +#### How to Fix + +Provide a valid [Port][] between the [Int32][] values 1 and 65535 in the [ServerDetails][] and ensure that the mail server is up and running without issues. + +*** + +### Invalid Host {#101} + +A [Category][] of `Socket` and an [Error Code][] of `101` indicates that the [Host][] provided in the [ServerDetails][] is invalid. + +#### Message Format + +```json +"Invalid 'Host' ('') provided. The 'Server Details' in 'Email Session Details' has been provided a host that does not exist. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the address of the mail server that a session is being opened with + +#### How to Fix + +Provide a valid [Host][] in the [ServerDetails][]. + +*** + +### SSL Required {#200} + +A [Category][] of `SSL` and an [Error Code][] of `200` indicates that [SSL][] is required. More specifically, the mail server is expecting that [SSL][] is used as soon as the connection is established. + +#### Message Format + +```json +"The connection could not be established or disconnected unexpectedly. Check if the 'Port' () provided requires that 'Use SSL' be set to true. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the port on the mail server that a session is being opened with + +#### How to Fix + +Change [UseSsl][] in the [ServerDetails][] to `true`, or make a connection on a [Port][] which does not require [SSL][]. + +*** + +### SSL Unsupported {#201} + +A [Category][] of `SSL` and an [Error Code][] of `201` indicates that one of the following issues occurred: + +- An [SSL][] connection is not supported. More specifically, the mail server either does not support [SSL][] connections or only supports [SSL][] connections via the STARTTLS command. +- Certificate on the [Host][] is expired, untrusted or invalid +- Certificate replaced by anti-virus software in order to scan web traffic resulting in failed certificate validation +- [CRL][] server is down + +#### Message Format + +```json +"The connection could not be established or disconnected unexpectedly. Check if the 'Port' () provided requires that 'Use SSL' be set to false. If this is not the case, check the inner exception. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the port on the mail server that a session is being opened with + +#### How to Fix + +Change [UseSsl][] in the [ServerDetails][] to `false`, or make a connection on a port which supports [SSL][]. + +If the above suggestion does not fix the problem, check if the anti-virus software on the server executing the flow is replacing the [SSL][] certificate in order to scan the web traffic, and change the settings appropriately if needed. + +If the issue persists, please check the inner exception as instructed by the [Message][]. + +*** + +### Invalid User Credentials {#300} + +A [Category][] of `UserCredentials` and an [Error Code][] of `300` indicates that the [Username][] and [Password][] combination provided in the [UserCredentials][] is invalid. + +#### Message Format + +```json +"The provided 'Username' and 'Password' is incorrect. The 'User Credentials' in 'Email Session Details' has been provided an incorrect username and password combination. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to Fix + +Provide a valid [Username][] and [Password][] combination in the [UserCredentials][]. + +*** + +### Invalid SSL Certificate {#400} + +A [Category][] of `OAuthCredentials` and an [Error Code][] of `400` indicates that one of the following issues occurred: + +- An invalid [CertificatePath][] and [CertificatePassword][] combination has been provided in the [GmailOAuthCertificateCredentials][] +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] points to an invalid [SSL][] certificate +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] points to a non-existant file +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] points to a folder +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] is longer than the system defined maximum length (typically 32,767) +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] contains only whitespace (i.e. `" "`) or contains the NUL character (i.e. `\0`) +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] contains leading spaces +- The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] contains invalid characters (i.e. `"`, `*`, `?`, `\|`, `<`, `>`, `:`, `\`, `/`) +- Access is denied to the file at the [CertificatePath][] in the [GmailOAuthCertificateCredentials][] + +#### Message Format + +```json +"The 'Certificate Path' ('') or 'Certificate Password' is invalid. The 'Gmail OAuth Certificate Credentials' in 'Email Session Details' has been provided an incorrect certificate path or certificate password. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the path pointing to the [SSL][] certificate + +#### How to Fix + +Provide a [CertificatePath][] which is a valid file path pointing to a valid [SSL][] certificate and ensure that the [CertificatePassword][] is correct in the [GmailOAuthCertificateCredentials][]. + +*** + +### Invalid Gmail Client Credentials {#401} + +A [Category][] of `OAuthCredentials` and an [Error Code][] of `401` indicates that an invalid [FromAddress][] and [ClientId][] combination has been provided in the [GmailOAuthCertificateCredentials][]. + +#### Message Format + +```json +"The 'From Address' ('}') or 'Client Id' ('') is invalid. The 'Gmail OAuth Certificate Credentials' in 'Email Session Details' has been provided an incorrect email address or Client ID. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the email address to send the email from +- `` is the client ID for the client application + +#### How to Fix + +Provide a valid [FromAddress][] and ensure that the [ClientId][] is correct in the [GmailOAuthCertificateCredentials][]. + +*** + +## Properties + +### Exception Type + +The type of the exception (i.e. `EmailSessionException`) + +| | | +|-----------|------------| +| 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 `EmailSessionException` there are the following categories: + +- `Socket` +- `SSL` +- `UserCredentials` +- `OAuthCredentials` + +| | | +|-----------|------------| +| 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 `EmailSessionException` there are the following error codes: + +- [100][InvalidPortProvided] - indicates that the [Port][] provided in the [ServerDetails][] is invalid +- [101][InvalidHostProvided] - indicates that the [Host][] provided in the [ServerDetails][] is invalid +- [200][SslWrappedConnectionRequired] - indicates that [SSL][] is required +- [201][SslWrappedConnectionNotSupported] - indicates that an [SSL][] connection is not supported +- [300][InvalidUsernameAndPassword] - indicates that the [Username][] and [Password][] combination provided in in the [UserCredentials][] is invalid +- [400][InvalidSslCertificate] - indicates that the [CertificatePath][] or [CertificatePassword][] provided in the [GmailOAuthCertificateCredentials][] is invalid +- [401][InvalidClientCredentials] - indicates that the [FromAddress][] or [ClientId][] provided in the [GmailOAuthCertificateCredentials][] is invalid + +| | | +|-----------|---------------------------| +| Data Type | [EmailSessionErrorCode][] | + +### 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 + +- [BasicEmailSessionDetails][] +- [EmailSessionErrorCode][] +- [GmailOAuthCertificateCredentials][] +- [GmailSessionDetails][] +- [Int32][] +- [ServerDetails][] +- [String][] +- [UserCredentials][] + +### Related Concepts + +- [Exceptions][] +- [Working with Email][] + +### Related Blocks + +- [Send Email Using SMTP Server Block][] +- [Send Email Using Gmail Block][] +- [Send Email Using Microsoft 365 Block][] + +### External Documentation + +None + +[InvalidPortProvided]: {{< ref "#100">}} +[InvalidHostProvided]: {{< ref "#101">}} +[SslWrappedConnectionRequired]: {{< ref "#200">}} +[SslWrappedConnectionNotSupported]: {{< ref "#201">}} +[InvalidUsernameAndPassword]: {{< ref "#300">}} +[InvalidSslCertificate]: {{< ref "#400">}} +[InvalidClientCredentials]: {{< ref "#401">}} +[Message]: {{< ref "#message" >}} +[Category]: {{< ref "#category" >}} +[Error Code]: {{< ref "#error-code" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[GmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails.MainDoc" >}} +[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" >}} +[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" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} +[BasicEmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.MainDoc" >}} +[EmailSessionErrorCode]: {{< url path="Cortex.Reference.DataTypes.Email.EmailSessionErrorCode.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Send Email Using SMTP Server Block]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.MainDoc" >}} +[Send Email Using Gmail Block]: {{< url path="Cortex.Reference.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmail.MainDoc" >}} +[Send Email Using Microsoft 365 Block]: {{< url path="Cortex.Reference.Blocks.Microsoft365.Outlook.SendEmail.SendEmailUsingMicrosoft365.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[CRL]: {{< url path="Cortex.Reference.Glossary.A-E.CRL" >}} +[SSL]: {{< url path="Cortex.Reference.Glossary.P-T.SSL" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/_index.md b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/_index.md new file mode 100644 index 000000000..74b90995f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/_index.md @@ -0,0 +1,5 @@ +--- +title: "Files & Folders" +linkTitle: "Files & Folders" +description: "Exceptions related to Files and Folders" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-folder-name-exception.md b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-folder-name-exception.md new file mode 100644 index 000000000..531a06843 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-folder-name-exception.md @@ -0,0 +1,55 @@ +--- +title: "InvalidFolderNameException" +linkTitle: "InvalidFolderNameException" +description: "The exception thrown when a folder name is invalid." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.FilesAndFolders.InvalidFolderNameException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when specifying an invalid folder name. + +## Reasons + +### Invalid folder name provided + +The folder name provided is invalid. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The '' given was ''; this is not a valid folder name. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the folder name which threw this exception. +* `` is the value of the property, i.e. the folder name, which was invalid. + +#### How to fix + +Ensure that the folder name provided is a valid folder name; please see [Naming Conventions][] for more information. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [Naming Files, Paths, and Namespaces][NamingFilesPathsAndNamespaces] + +[FolderConcepts]: {{}} +[WhatIsAPath]: {{}} +[Naming Conventions]: {{}} +[NamingFilesPathsAndNamespaces]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md new file mode 100644 index 000000000..f5bcc9286 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/invalid-path-exception.md @@ -0,0 +1,78 @@ +--- +title: "InvalidPathException" +linkTitle: "InvalidPathException" +description: "The exception thrown when a file or folder path is invalid." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.FilesAndFolders.InvalidPathException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when specifying an invalid file or folder [path][WhatIsAPath]. + +## Reasons + + +### Path provided is invalid + +The provided [path][WhatIsAPath] has an incorrect syntax, or has illegal characters, or is too long. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The '' given was ''; this is not a valid folder path. Please see the 'InnerException' property for more details. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the path which threw this exception. +* `` is the value of the property, i.e. the path, which was invalid. + +#### How to fix + +Ensure that the [path][WhatIsAPath] provided has no incorrect syntax or illegal characters, and that it is not too long; see [Paths][] for more information. + +### Path provided must represent a folder and that path must not point to an existing file + +The provided [path][WhatIsAPath] needs to be a folder, and must not point to an existing file. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The '' given was ''; this is not a valid folder path. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the path which threw this exception. +* `` is the value of the property, i.e. the path, which was invalid. + +#### How to fix + +Ensure that the [path][WhatIsAPath] provided is a valid folder path and does not point to an existing file; see [Paths][] for more information. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [Naming Files, Paths, and Namespaces][NamingFilesPathsAndNamespaces] + +[FolderConcepts]: {{}} +[WhatIsAPath]: {{}} +[NamingFilesPathsAndNamespaces]: {{}} +[Paths]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md new file mode 100644 index 000000000..419e837ef --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/files-and-folders/operation-failed-exception.md @@ -0,0 +1,83 @@ +--- +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)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a file or folder operation failed for one or more paths. + +## Reasons + +### A single exception was thrown + +An exception was thrown, such as [InvalidFolderNameException][] or [InvalidPathException][], while performing an operation on the path provided. + +#### Message Format + +The format of the message is as follows: + +```json +"Failed to the path. Please see the 'PathExceptions' property for details on why the operation failed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the action taking place when the operation failed (i.e. `copy`, `create`, `delete`, `duplicate`, `get`, `move`, `read`, `rename`, `search`, `write`). + +#### How to fix + +The exception that caused the operation to fail can be seen in the `PathExceptions` property; for how to fix, please refer to the exception's HelpLink. + +### Multiple exceptions were thrown + +Multiple exceptions were thrown, such as [InvalidFolderNameException][] or [InvalidPathException][], while performing operations on the paths provided. + +#### Message Format + +The format of the message is as follows: + +```json +"Failed to of paths. Please see the 'PathExceptions' property for details on why each operation failed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the action taking place when the operation failed (i.e. `copy`, `create`, `delete`, `duplicate`, `get`, `move`, `read`, `rename`, `search`, `write`). +* `` is the number of paths that were attempted to be operated on where the operation failed (e.g. `2`). +* `` is the total number of paths that were attempted to be operated on (e.g. `5`). + +#### How to fix + +The exceptions that caused the operations to fail can be seen in the `PathExceptions` property; for how to fix, please refer to each exception's HelpLink. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[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" >}} + +[InvalidFolderNameException]: {{}} +[InvalidPathException]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/_index.md b/content/en/docs/2024.9/Reference/Exceptions/flows/_index.md new file mode 100644 index 000000000..1a32688c8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/_index.md @@ -0,0 +1,5 @@ +--- +title: "Flows" +linkTitle: "Flows" +description: "Exceptions related to Flows" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/_index.md b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/_index.md new file mode 100644 index 000000000..7d6adb34d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/_index.md @@ -0,0 +1,5 @@ +--- +title: "Blocks" +linkTitle: "Blocks" +description: "Exceptions related to Blocks" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/block-timeout-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/block-timeout-exception.md new file mode 100644 index 000000000..4b967e686 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/block-timeout-exception.md @@ -0,0 +1,175 @@ +--- +title: "BlockTimeoutException" +linkTitle: "BlockTimeoutException" +description: "The exception thrown when the execution of a block exceeds the specified block timeout." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.Blocks.BlockTimeoutException)

+ +## Description + +The exception thrown when the execution of a block exceeds the specified block timeout. + +## Reasons + +### Block Timeout Reached + +Executing the block took longer than the [Block Timeout][]. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The block timed out because its execution time reached the Block Timeout of milliseconds. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the [block timeout][Block Timeout Property] for the block that threw the exception, in milliseconds. + +#### How to fix + +Ensure the action that the block is taking is likely to complete within the given [TimePeriod][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `BlockTimeoutException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Block Timeout + +The period of time in which a block must finish execution before timing out. + +| | | +|-----------|------------| +| Data Type | [TimePeriod][] | + +### ExecutionId + +The Id of the [execution][WhatIsAnExecution] running the block that has timed out. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### FlowId + +The Id of the [flow][WhatIsAFlow] containing the block that has timed out. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### WorkspaceId + +The Id of the [workspace][WhatIsAWorkspace] containing the block that has timed out. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### BlockId + +The Id of the [block][WhatIsABlock] that has timed out. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### 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 + +* Date & Time + * [TimePeriod][] +* Text + * [String][] +* Other + * [Guid][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Block Timeout Property][Block Timeout] +* [Exceptions][] +* [Executions][] +* [Flows][] +* [Workspaces][] + +### Related Blocks + +All Blocks except: + +* Flows + * [Start Flow][] + * [End Flow][] +* Schedules + * [Wait For Duration][] +* Workspaces + * [Start Workspace][] + * [End Workspace][] + +### External Documentation + +None + +[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" >}} + +[Block Timeout Property]: {{}} +[InnerException]: {{< ref "#innerexception" >}} +[Message]: {{< ref "#message" >}} + +[Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Block Timeout]: {{}} +[Executions]: {{}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Flows]: {{}} +[Workspaces]: {{}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Guid]: {{}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} + +[WhatIsABlock]: {{}} +[WhatIsAFlow]: {{}} +[WhatIsAnExecution]: {{}} +[WhatIsAWorkspace]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md new file mode 100644 index 000000000..438e2e8ac --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/invalid-block-timeout-exception.md @@ -0,0 +1,145 @@ +--- +title: "InvalidBlockTimeoutException" +linkTitle: "InvalidBlockTimeoutException" +description: "The exception thrown when a block timeout is invalid." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.Blocks.InvalidBlockTimeoutException)

+ +## Description + +The exception thrown when a block timeout is invalid. + +## Reasons + +### Block Timeout Out of Range + +The [Block Timeout][Block Timeout Property] provided for the block is either negative or greater than the maximum value allowed, which is the [Int32][] maximum of `2,147,483,647`. + +#### Message Format + +The format of the [Message][] is as follows: + +```json +"The provided TimePeriod for the BlockTimeout equates to milliseconds which is invalid; it must be a non-negative value less than 2,147,483,647. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the timeout of the affected block in milliseconds. + +#### How to fix + +Ensure that the affected block has a block timeout that is non-negative and less than the maximum allowed [TimePeriod][]. + +## Properties + +### Exception Type + +The type of the exception (i.e. `InvalidBlockTimeoutException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Block ID + +The ID of the block with an invalid timeout. + +| | | +|-----------|------------| +| Data Type | [Guid][] | + +### Duration + +The duration in milliseconds that the block timeout provided to the block evaluated to. + +| | | +|-----------|------------| +| Data Type | [Double][] | + +### 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 + +* Date & Time + * [TimePeriod][] +* Numbers + * [Double][] + * [Int32][] +* Text + * [String][] +* Other + * [Guid][] + +### Related Concepts + +* [Blocks][] +* [Block Properties][] +* [Block Timeout Property][Block Timeout] +* [Exceptions][] + +### Related Blocks + +All Blocks except: + +* Flows + * [Start Flow][] + * [End Flow][] +* Schedules + * [Wait For Duration][] +* Workspaces + * [Start Workspace][] + * [End Workspace][] + +### External Documentation + +None + +[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 Timeout]: {{}} +[Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Block Timeout Property]: {{}} + +[Message]: {{< ref "#message" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Double]: {{}} +[Guid]: {{}} +[Int32]: {{}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/invalid-property-value-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/blocks/invalid-property-value-exception.md new file mode 100644 index 000000000..1141eb770 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/flows/execution/_index.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/_index.md new file mode 100644 index 000000000..5ab4664a7 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/flows/execution/flow-execution-cancelled-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/flow-execution-cancelled-exception.md new file mode 100644 index 000000000..b3e981b39 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/flows/execution/invalid-default-values-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/invalid-default-values-exception.md new file mode 100644 index 000000000..ee26bfcb9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/invalid-default-values-exception.md @@ -0,0 +1,42 @@ +--- +title: "InvalidDefaultValuesException" +linkTitle: "InvalidDefaultValuesException" +description: "The exception thrown if an exception occurs when initialising the default value for a variable." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.Execution.InvalidDefaultValuesException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown if an exception occurs when initialising the default value for a variable. + +## Reasons + +### Invalid Default Variable Value + +The default value provided for a variable is invalid. + +#### Message Format + +```json +"Failed to initialise variables due to invalid default values. Please see the 'Variables' property for details on why each variable threw." +``` + +#### How to fix + +Ensure that the variables shown in the `Variables` property have valid default values, by fixing the inner exception for each variable shown. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/execution/invalid-input-variables-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/invalid-input-variables-exception.md new file mode 100644 index 000000000..17bf5fe56 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/flows/execution/output-port-not-connected-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/output-port-not-connected-exception.md new file mode 100644 index 000000000..92369eabd --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/output-port-not-connected-exception.md @@ -0,0 +1,47 @@ +--- +title: "OutputPortNotConnectedException" +linkTitle: "OutputPortNotConnectedException" +description: "The exception thrown when an execution tries to go through an output port which is not connected." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.Execution.OutputPortNotConnectedException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an execution tries to go through an [output port][Block Connections] which is not connected. + +## Reasons + +### Output port not connected + +The [output port][Block Connections] of a block in a flow is not connected to another block. + +#### Message Format + +The format of the message is as follows: + +```json +"Block output port isn't connected. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure that the block that threw this exception has its output port connected to another block; see [Block Connections][] for more information. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[Block Connections]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/execution/runtime-translation-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/runtime-translation-exception.md new file mode 100644 index 000000000..6048bb2a4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/execution/runtime-translation-exception.md @@ -0,0 +1,45 @@ +--- +title: "RuntimeTranslationException" +linkTitle: "RuntimeTranslationException" +description: "The exception thrown when a block is found to have errors within its properties while executing a flow." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.Execution.RuntimeTranslationException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a block is found to have errors within its properties while executing a flow. +## Reasons + +### Block has errors during flow execution + +A block was found to have errors within its properties during a flow execution. These errors would normally appear as a [Message][WhatIsAMessage], but were not caught when the flow execution was started. This can occur when debugging a flow and [setting the next block to execute][SetNextBlockToExecute] to a block that has errors within its properties, and has no path from the [Start Flow][Start Flow block] block. + +#### Message Format + +```json +"The block could not be executed because there are errors within its properties. Note that this was not caught when the flow was started either because there is no path from the start of the flow to this block, or the property values in the block." +``` + +#### How to fix + +Ensure that the errors in the properties within the block which caused this exception to be thrown, as seen within the `FailedTranslationSummary` property of this exception, are fixed (e.g. ensure that all variables referenced in the block properties are declared and initialised as expected). + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[WhatIsAMessage]: {{}} +[SetNextBlockToExecute]: {{}} +[Start Flow block]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/flows/flow-exception.md b/content/en/docs/2024.9/Reference/Exceptions/flows/flow-exception.md new file mode 100644 index 000000000..d1439839d --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/flows/flow-exception.md @@ -0,0 +1,50 @@ +--- +title: "FlowException" +linkTitle: "FlowException" +description: "The exception thrown by the Throw New Flow Exception block." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Flows.FlowException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown by the [Throw New Flow Exception][ThrowNewFlowException Block] block. + +## Reasons + +### Thrown by block + +An instance of the [Throw New Flow Exception][ThrowNewFlowException Block] block has been executed in a flow. + +#### Message Format + +The format of the exception message is as follows: + +```json +"" +``` + +where: + +* `` is the user-defined message specified by the `Message` property of the [Throw New Flow Exception][ThrowNewFlowException Block] block. + +#### How to fix + +Ensure that the issue which caused the execution to progress through to the [Throw New Flow Exception][ThrowNewFlowException Block] block is resolved. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[ThrowNewFlowException Block]: {{}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/http/_index.md b/content/en/docs/2024.9/Reference/Exceptions/http/_index.md new file mode 100644 index 000000000..9d4e1a2b8 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/http/http-authorisation-exception.md b/content/en/docs/2024.9/Reference/Exceptions/http/http-authorisation-exception.md new file mode 100644 index 000000000..831750b98 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/http/http-authorisation-exception.md @@ -0,0 +1,111 @@ +--- +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)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an issue occurs during the authorisation process when working with HTTP. + +There are multiple reasons that this exception can be thrown: + +* [Invalid Access Token Uri][] +* [Invalid Client ID or Client Secret][] +* [Invalid Resource Owner Username or Password][] + +## Reasons + +### Invalid Access Token Uri {#httpoauthcredentialsaccesstokenuri} + +An invalid access token uri was provided. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid 'Access Token Uri' (\"\") provided. A token could not be retrieved from the provided 'Access Token Uri'. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the uri provided from which the block is attempting to retrieve an access token. + +#### How to fix + +Ensure that the uri provided is valid. + +### Invalid Client ID or Client Secret {#httpoauthclientcredentialsclientauthentication} + +The client ID or client secret in the [HttpOAuthClientCredentials][] provided are invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' (\"\") or '' provided. A token could not be retrieved from the provided 'Access Token Uri' (\"\") using these credentials. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the possibly invalid client ID for the credentials provided. +* `` is the value of the possibly invalid client ID for the credentials provided. +* `` is the name of property containing the possibly invalid client secret for the credentials provided. +* `` is the uri provided from which the block is attempting to retrieve an access token. + +#### How to fix + +Ensure that the credentials provided for client authentication contains a valid client ID and client secret. + +### Invalid Resource Owner Username or Password {#httpoauthpasswordcredentialsresourceowner} + +The username or password for the resource owner in the [HttpOAuthPasswordCredentials][] provided are invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' (\"\") or '' provided. A token could not be retrieved from the provided 'Access Token Uri' (\"\") using these credentials. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the possibly invalid username for the credentials provided. +* `` is the value of the possibly invalid username for the credentials provided. +* `` is the name of property containing the possibly invalid password for the credentials provided. +* `` is the uri provided from which the block is attempting to retrieve an access token. + +#### How to fix + +Ensure that the credentials provided for the resource owner contains a valid username and password. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[Invalid Access Token Uri]: {{}} +[Invalid Resource Owner Username or Password]: {{}} +[Invalid Client ID or Client Secret]: {{}} + +[HttpOAuthCredentials]: {{}} +[HttpOAuthClientCredentials]: {{}} +[HttpOAuthPasswordCredentials]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/http/invalid-request-exception.md b/content/en/docs/2024.9/Reference/Exceptions/http/invalid-request-exception.md new file mode 100644 index 000000000..e9206f8a5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/http/invalid-request-exception.md @@ -0,0 +1,335 @@ +--- +title: "InvalidRequestException" +linkTitle: "InvalidRequestException" +description: "The exception thrown when an issue occurs with an HTTP request or a SOAP request." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Http.InvalidRequestException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an issue occurs with an [HTTP request][HttpRequest] or a [SOAP request][SoapRequest]. + +There are multiple reasons that this exception can be thrown: + +* [Invalid Headers in HTTP Request][] +* [Invalid Headers in SOAP Request][] +* [Invalid HTTP Version in HTTP Request][] +* [Invalid HTTP Version in SOAP Request][] +* [Invalid Request Body in HTTP Request][] +* [Invalid Request Envelope in SOAP Request][] +* [Invalid Request Verb in HTTP Request][] +* [Invalid Uri in HTTP Request][] +* [Invalid Uri in SOAP Request][] + +## Reasons + +### Invalid Headers in HTTP Request {#httprequestheaders} + +The [Headers][HttpRequestHeaders] provided in the [HttpRequest][HttpRequest] are invalid (e.g. a header key in the headers is empty). + +#### Message Format + +The format of the message can be one of the following: + +```json +"Invalid 'Headers' provided. A header key has been provided which is empty. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") that cannot be assigned to its property. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") has been provided a header value (\"\") that cannot be converted to its property type (\"\"). +Please click the HelpLink for more information on how to fix this." +``` + +or + +[//]: # (forbidden header key route, implemented and technically valid though no header keys are currently set as forbidden so will never be thrown) + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") has been provided which is forbidden. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the specific header key in the request headers which may be invalid or contain an invalid value. +* `` is the value assigned to the header with the given key, which may be invalid. +* `` is the expected data type for the header value. + +#### How to fix + +* Ensure that the header key is not empty. +* Ensure that the value provided for the header is valid (e.g. the `"Host"` key expects string in a uri format, so `"27/03/2024"` would not be a valid value, while `"https://www.example.com"` would). +* Ensure that the value provided for the header is of the correct type (e.g. the `"Date"` key expects a value that can convert to [DateTime][DateTime], so `0` is not a valid value, while a string of format `"dd-mm-yyyy"` such as `"13-03-2024"` is). +* Ensure that no forbidden header keys are provided in the request. + +[//]: # (TODO add a list of forbidden header keys, and explain what forbidden header keys are - i.e. they can't be set) + +### Invalid Headers in SOAP Request {#soaprequestheaders} + +The [Headers][SoapRequestHeaders] provided in the [SoapRequest][SoapRequest] are invalid (e.g. a header key in the headers is empty). + +#### Message Format + +The format of the message can be one of the following: + +```json +"Invalid 'Headers' provided. A header key has been provided which is empty. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") that cannot be assigned to its property. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") has been provided a header value (\"\") that cannot be converted to its property type (\"\"). +Please click the HelpLink for more information on how to fix this." +``` + +or + +[//]: # (forbidden header key route, implemented and technically valid though no header keys are currently set as forbidden so will never be thrown) + +```json +"Invalid 'Headers' provided. A restricted header key (\"\") has been provided which is forbidden. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the specific header key in the request headers which may be invalid or contain an invalid value. +* `` is the value assigned to the header with the given key, which may be invalid. +* `` is the expected data type for the header value. + +#### How to fix + +* Ensure that the header key is not empty. +* Ensure that the value provided for the header is valid (e.g. the `"Host"` key expects string in a uri format, so `"27/03/2024"` would not be a valid value, while `"https://www.example.com"` would). +* Ensure that the value provided for the header is of the correct type (e.g. the `"Date"` key expects a value that can convert to [DateTime][DateTime], so `0` is not a valid value, while a string of format `"dd-mm-yyyy"` such as `"13-03-2024"` is). +* Ensure that no forbidden header keys are provided in the request. + +[//]: # (TODO add a list of forbidden header keys, and explain what forbidden header keys are - i.e. they can't be set) + +### Invalid HTTP Version in HTTP Request {#httprequesthttpversion} + +The [HttpVersion][HttpRequestHttpVersion] provided in the [HttpRequest][HttpRequest] is invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' provided. The '' \"\" is not a valid Http Request Version. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the property containing the invalid HTTP version value. +* `` is the invalid value for the HTTP version. + +#### How to fix + +Ensure that the [HttpVersion][HttpRequestHttpVersion] provided for the [HttpRequest][HttpRequest] is a valid version (i.e. `HTTP10` or `HTTP11`). + +### Invalid HTTP Version in SOAP Request {#soaprequesthttpversion} + +The [HttpVersion][SoapRequestHttpVersion] provided in the [SoapRequest][SoapRequest] is invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' provided. The '' \"\" is not a valid Http Request Version. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the property containing the invalid HTTP version value. +* `` is the invalid value for the HTTP version. + +#### How to fix + +Ensure that the [HttpVersion][SoapRequestHttpVersion] provided for the [SoapRequest][SoapRequest] is a valid version (i.e. `HTTP10` or `HTTP11`). + +### Invalid Request Body in HTTP Request {#httprequestbody} + +The [Body][HttpRequestBody] provided for the [HttpRequest][HttpRequest] was invalid (i.e. a body was provided for a [Verb][HttpRequestVerb] which does not accept a body, or the body was invalid for the [ContentType][HttpRequestContentType]). + +#### Message Format + +The format of the message can be one of the following: + +```json +"Invalid 'Body' provided. The 'Verb' \"\" should not be provided a 'Body'. +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"Invalid 'Body' provided. The 'Body' does not match the 'Content Type' \"\". +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the request verb of the errored request. +* `` is the content type of the request (e.g. XML, JSON, etc). + +#### How to fix + +* Ensure that no [Body][HttpRequestBody] is provided for `GET` and `HEAD` requests. +* Ensure that the content of the [Body][HttpRequestBody] is valid for the [ContentType][HttpRequestContentType] specified (e.g. the [Body][HttpRequestBody] is valid JSON if the [ContentType][HttpRequestContentType] is `application/json`). + +### Invalid Request Envelope in SOAP Request {#soaprequestsoapmessageenvelope} + +The [Envelope][RequestEnvelope] provided in the [SoapMessage][SoapRequestSoapMessage] for the [SoapRequest][SoapRequest] is not valid XML. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid 'Envelope' provided. The 'Envelope' is not valid XML. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure that the [Envelope][RequestEnvelope] provided is valid XML. + +### Invalid Request Verb in HTTP Request {#httprequestverb} + +The [Verb][HttpRequestVerb] provided for the [HttpRequest][HttpRequest] is invalid. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' provided. The '' \"\" is not a valid Request Verb. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the invalid verb. +* `` is the value of the invalid verb. + +#### How to fix + +Ensure that the [Verb][HttpRequestVerb] provided is a valid [RequestVerb][RequestVerb] (i.e. `GET`, `POST`, `PUT`, `DELETE`, `PATCH` or `HEAD`). + +### Invalid Uri in HTTP Request {#httprequesturi} + +The [Uri][HttpRequestUri] provided for the [HttpRequest][HttpRequest] cannot be parsed. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' (\"\") provided. The '' has been provided a uri that cannot be parsed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the invalid uri. +* `` is the value of the uri provided that could not be parsed. + +#### How to fix + +Ensure that the [Uri][HttpRequestUri] provided is a valid uri (i.e. it is of the [correct format][UriSyntax] and contains no [invalid characters][UriInvalidCharacters]). + +### Invalid Uri in SOAP Request {#soaprequesturi} + +The [Uri][SoapRequestUri] provided for the [SoapRequest][SoapRequest] cannot be parsed. + +#### Message Format + +The format of the message is as follows: + +```json +"Invalid '' (\"\") provided. The '' has been provided a uri that cannot be parsed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the invalid uri. +* `` is the value of the uri provided that could not be parsed. + +#### How to fix + +Ensure that the [Uri][SoapRequestUri] provided is a valid uri (i.e. it is of the [correct format][UriSyntax] and contains no [invalid characters][UriInvalidCharacters]). + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [RFC 3986 Section 2: Characters][UriInvalidCharacters] +* [Syntax of Uniform Resource Identifiers (URIs)][UriSyntax] + +[Invalid Headers in HTTP Request]: {{}} +[Invalid Headers in SOAP Request]: {{}} +[Invalid HTTP Version in HTTP Request]: {{}} +[Invalid HTTP Version in SOAP Request]: {{}} +[Invalid Request Body in HTTP Request]: {{}} +[Invalid Request Envelope in SOAP Request]: {{}} +[Invalid Uri in HTTP Request]: {{}} +[Invalid Uri in SOAP Request]: {{}} +[Invalid Request Verb in HTTP Request]: {{}} + +[DateTime]: {{}} +[Enum]: {{}} + +[HttpRequest]: {{}} +[HttpRequestBody]: {{}} +[HttpRequestContentType]: {{}} +[HttpRequestHeaders]: {{}} +[HttpRequestUri]: {{}} +[HttpRequestVerb]: {{}} +[HttpRequestHttpVersion]: {{}} + +[SoapRequest]: {{}} +[SoapRequestHeaders]: {{}} +[SoapRequestHttpVersion]: {{}} +[SoapRequestSoapMessage]: {{}} +[SoapRequestUri]: {{}} + +[RequestEnvelope]: {{}} +[RequestVerb]: {{}} +[HttpRequestVersion]: {{}} +[Execute Soap Request]: {{}} + +[UriSyntax]: {{}} +[UriInvalidCharacters]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/http/invalid-response-exception.md b/content/en/docs/2024.9/Reference/Exceptions/http/invalid-response-exception.md new file mode 100644 index 000000000..9334d380a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/http/invalid-response-exception.md @@ -0,0 +1,49 @@ +--- +title: "InvalidResponseException" +linkTitle: "InvalidResponseException" +description: "The exception thrown when an issue occurs with an HTTP response." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Http.InvalidResponseException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an issue occurs with an HTTP response. + +## Reasons + +### Response envelope in SOAP response is not valid XML + +The [response envelope][ResponseEnvelope] returned from a SOAP response is not valid XML. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Invalid 'Response Envelope' returned. The 'Response Envelope' is not valid XML. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +The SOAP Web Service returning the [SoapResponse][] must be fixed to return valid XML in the [response envelope][ResponseEnvelope]. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[ExecuteSOAPRequestBlock]: {{}} +[SoapResponse]: {{}} +[ResponseEnvelope]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/impersonation/_index.md b/content/en/docs/2024.9/Reference/Exceptions/impersonation/_index.md new file mode 100644 index 000000000..87ab370f1 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/impersonation/run-as-exception.md b/content/en/docs/2024.9/Reference/Exceptions/impersonation/run-as-exception.md new file mode 100644 index 000000000..f4b0eab52 --- /dev/null +++ b/content/en/docs/2024.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: , see the inner exception for more information. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the native error code present in the [Win32Exception][] inner-exception. + +#### How to fix + +Make sure that the provided domain, username and password in the [UserCredentials][] are correct. + +## Properties + +### Exception Type + +The type of the exception (i.e. `RunAsException`). + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Error Code + +The error code for the exception, which is used to indicate the reason that the exception occurred. + +For `RunAsException` there are the following error codes: + +- [1326][InvalidCredentialsProvided] - indicates that the domain, user name or password is incorrect. + +| | | +|-----------|---------------------------| +| Data Type | [Int32][] | + +### Inner Exception + +The Inner Exception is the [Exception][] instance that caused the current [Exception][], and contains specific details about the problem. + +| | | +|-----------|------------| +| Data Type | [Win32Exception][] | + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## See Also + +### Related Data Types + +* [UserCredentials][] +* [String][] +* [Int32][] + +### Related Concepts + +* [Exceptions][] +* [Common Properties][] + +### Related Blocks + +* [All Blocks][] + +Except: + +* [End Flow][] +* [End Workspace][] +* [Handle Flow Exception][] +* [Start Flow][] +* [Wait For Duration][] + +### External Documentation + +* [Win32Exception][] + +[Message]: {{< ref "#message" >}} +[InvalidCredentialsProvided]: {{< ref "#1326">}} + +[All Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[FlowException]: {{< url path="Cortex.Reference.Exceptions.Flows.FlowException.MainDoc" >}} +[RunAsException]: {{< url path="Cortex.Reference.Exceptions.Impersonation.RunAsException.MainDoc" >}} +[Win32Exception]: {{< url path="MSDocs.DotNet.Api.System.ComponentModel.Win32Exception" >}} +[Common Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.MainDoc" >}} +[Run As Property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.RunAsProperty" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} + +[Scopes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Scopes.MainDoc" >}} + +[End Flow]: {{< url path="Cortex.Reference.Blocks.Flows.EndFlow.EndFlow.MainDoc" >}} +[End Workspace]: {{< url path="Cortex.Reference.Blocks.Workspaces.EndWorkspace.EndWorkspace.MainDoc" >}} +[Handle Flow Exception]: {{< url path="Cortex.Reference.Blocks.Exceptions.HandleFlow.HandleFlowException.MainDoc" >}} +[Start Flow]: {{< url path="Cortex.Reference.Blocks.Flows.StartFlow.StartFlow.MainDoc" >}} +[Wait For Duration]: {{< url path="Cortex.Reference.Blocks.Schedules.WaitFor.WaitForDuration.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/loops/_index.md b/content/en/docs/2024.9/Reference/Exceptions/loops/_index.md new file mode 100644 index 000000000..9a6b00125 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/loops/_index.md @@ -0,0 +1,5 @@ +--- +title: "Loops" +linkTitle: "Loops" +description: "Exceptions related to Loops." +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/loops/infinite-loop-exception.md b/content/en/docs/2024.9/Reference/Exceptions/loops/infinite-loop-exception.md new file mode 100644 index 000000000..356445d64 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/loops/infinite-loop-exception.md @@ -0,0 +1,173 @@ +--- +title: "InfiniteLoopException" +linkTitle: "InfiniteLoopException" +description: "The exception thrown when an infinite loop can occur." +--- + +# {{% param title %}} + +

(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/2024.9/Reference/Exceptions/powershell/_index.md b/content/en/docs/2024.9/Reference/Exceptions/powershell/_index.md new file mode 100644 index 000000000..be92b8a05 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/powershell/ps-exception.md b/content/en/docs/2024.9/Reference/Exceptions/powershell/ps-exception.md new file mode 100644 index 000000000..758fafbb7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/powershell/ps-exception.md @@ -0,0 +1,53 @@ +--- +title: "PSException" +linkTitle: "PSException" +description: "The exception thrown when a terminating error occurs while executing scripts over WinRM." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.PowerShell.PSException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a terminating error occurs while executing scripts over WinRM. + +There is a single reason that this exception can be thrown: + +* [Invalid Script][] + +## Reasons + +### Invalid Script {#invalidscript} + +The PowerShell script provided is invalid (i.e. it contains unexpected or invalid tokens, or it is missing a necessary token). + +#### Message Format + +The format of the exception message is as follows: + +```json +"Invalid 'Script' provided. See the Data property for details on why the script failed to execute. +Please click the help link below for more information on how to fix this." +``` + +#### How to fix + +Fix the problems that caused the termination of the script during execution, as shown in the `Data` property under the `"Errors"` key. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[Invalid Script]: {{}} + +[MS PowerShell]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/powershell/ps-remoting-exception.md b/content/en/docs/2024.9/Reference/Exceptions/powershell/ps-remoting-exception.md new file mode 100644 index 000000000..9560e829f --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/powershell/ps-remoting-exception.md @@ -0,0 +1,337 @@ +--- +title: "PSRemotingException" +linkTitle: "PSRemotingException" +description: "The exception thrown when access is denied to a host when attempting to execute scripts over WinRM." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.PowerShell.PSRemotingException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when access is denied to a host when attempting to execute scripts over WinRM. + +There are multiple reasons that this exception can be thrown: + +* [Access Denied][AccessDenied] +* [Client Authentication Disabled][ClientAuthenticationDisabled] +* [Host Contains Invalid Characters][HostContainsInvalidCharacters] +* [Invalid Certificate][InvalidCertificate] +* [Invalid Credentials][InvalidCredentials] +* [Invalid DNS][InvalidDNS] +* [Invalid Domain][InvalidDomain] +* [Invalid Host IP Address][InvalidHostIPAddress] +* [Invalid Host Name][InvalidHostName] +* [Invalid Port][InvalidPort] +* [Invalid Protocol][InvalidProtocol] +* [Invalid PSConfiguration][InvalidPSConfiguration] + +## Reasons + +### Access Denied {#accessdenied} + +Access to the host provided was denied. + +#### Message Format + +The format of the exception message can be one of the following: + +```json +"Access denied to the 'Host' (\"\"). +Please click the help link below for more information on how to fix this." +``` + +or + +```json +"Access denied to the 'Host' (\"\"). Authentication is disabled on the Host's WinRM service. +Please click the help link below for more information on how to fix this." +``` + +[//]: # (can't demo this message. relies on machine restart just before) + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the authentication mechanism (i.e. `Kerberos` or `Negotiate`) used for connecting to the host. + +#### How to fix + +* Ensure that the credentials provided are valid for a user account with permissions to execute PowerShell scripts or cmdlets on the [Host][ServerDetailsHost]. +* Ensure that the authentication mechanism (i.e. `Kerberos` or `Negotiate`) used is not disabled on the host machine's WinRM service. + +### Client Authentication Disabled {#clientauthenticationdisabled} + +[//]: # (never tested or thrown? added docs since we technically can throw this. ) + +Kerberos authentication is disabled on the server where the [Execution Service][] is running. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). Kerberos Authentication is disabled on the WinRM client on the server where the Cortex Execution Service is running (). +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the NetBIOS name of the server where the [Execution Service][] is running. + +#### How to fix + +If possible, enable Kerberos Authentication on the server where the [Execution Service][Execution Service] is running. + +### Host Contains Invalid Characters {#hostcontainsinvalidcharacters} + +The hostname provided contains invalid characters. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Invalid 'Host' (\"\") provided. The 'Host' has been provided a hostname that contains invalid characters. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that the hostname does not contain invalid characters; see [Naming Conventions][NamingConventions] for more information. + +### Invalid Certificate {#invalidcertificate} + +The SSL certificate provided is invalid (e.g. the hostname provided does not match the common name on the certificate). + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). See the data property for details on why the a security error has occurred. +Please click the help link below for more information on how to fix this." +``` + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that certificate provided is valid. + +### Invalid Credentials {#invalidcredentials} + +[//]: # (never tested or thrown, added docs since we technically can throw this) + +The credentials provided for accessing the host are invalid. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Username' or 'Password' provided is incorrect, or requires a 'Domain'. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that the credentials provided are valid. + +### Invalid DNS {#invaliddns} + +The hostname provided could not be resolved. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Host' has been provided a hostname that could not be resolved. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that the hostname provided is valid. + +### Invalid Domain {#invaliddomain} + +The domain for the authentication credentials provided is invalid. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Domain' (\"\") is unavailable on the network. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the domain for the authentication credentials provided, which is invalid. + +#### How to fix + +Ensure that the domain provided is valid. + +### Invalid Host IP Address {#invalidhostipaddress} + +The hostname provided is in the form of an invalid or untrusted IP address. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Host' has been provided an IP address which is either invalid or has not been added to the WinRM TrustedHosts List on the server where the Cortex Execution Service is running (). +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the NetBIOS name of the server where the [Execution Service][] is running. + +#### How to fix + +Ensure that the IP address provided for the [Host][ServerDetailsHost] is valid, and that this IP address has been added to the WinRM TrustedHosts List on the server where the [Execution Service][] is running. + +### Invalid Host Name {#invalidhostname} + +The hostname provided is invalid. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Host' provided is unavailable on the network. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that the hostname provided is valid (i.e. that it exists and is available on the network). + +### Invalid Port {#invalidport} + +The port provided is invalid. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Host' is either not running, not listening on 'Port' , or requires communication over SSL. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the provided port on the host to connect (e.g. `443`, `5986`, etc.); see [ServerDetails][] for more information. + +#### How to fix + +Ensure that the port provided is a valid port (e.g. `443`, `5986`, etc.). + +### Invalid Protocol {#invalidprotocol} + +The [Host][ServerDetailsHost] requires communication over SSL, while the [UseSSL][ServerDetailsUseSSL] property in the [ServerDetails][ServerDetails] provided is `false`. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'Host' requires communication over SSL. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. + +#### How to fix + +Ensure that the [UseSSL][ServerDetailsUseSSL] property for the [ServerDetails][ServerDetails] is `true` and that valid credentials and a valid certificate are provided for access to the host. + +### Invalid PSConfiguration {#invalidpsconfiguration} + +The value of the [PSConfiguration][] property in the [PowerShellSessionDetails][] provided does not match any of the configured PowerShell session configurations on the [Host][ServerDetailsHost]. + +#### Message Format + +The format of the exception message is as follows: + +```json +"Access denied to the 'Host' (\"\"). The 'PSConfiguration' (\"\") has not been configured on the 'Host'. +Please click the help link below for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][ServerDetailsHost] property provided in the [ServerDetails][ServerDetails]. +* `` is the value of the [PSConfiguration][] property in the [PowerShellSessionDetails][] provided (i.e. the PowerShell session configuration that would be used by the host), which is invalid. + +#### How to fix + +Ensure that the [PSConfiguration][] provided matches a configured PowerShell session configuration on the [Host][ServerDetailsHost]. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +* [Naming conventions in Active Directory for computers, domains, sites, and OUs][NamingConventions] + +[AccessDenied]: {{}} +[ClientAuthenticationDisabled]: {{}} +[HostContainsInvalidCharacters]: {{}} +[InvalidHostName]: {{}} +[InvalidDomain]: {{}} +[InvalidCredentials]: {{}} +[InvalidCertificate]: {{}} +[InvalidHostIPAddress]: {{}} +[InvalidDNS]: {{}} +[InvalidPort]: {{}} +[InvalidPSConfiguration]: {{}} +[InvalidProtocol]: {{}} + +[PowerShellSessionDetails]: {{}} +[ServerDetails]: {{}} +[ServerDetailsHost]: {{}} +[ServerDetailsUseSSL]: {{}} + +[PSConfiguration]: {{}} + +[Execution Service]: {{}} + +[NamingConventions]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/services/_index.md b/content/en/docs/2024.9/Reference/Exceptions/services/_index.md new file mode 100644 index 000000000..b6926475d --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/services/service-does-not-exist-exception.md b/content/en/docs/2024.9/Reference/Exceptions/services/service-does-not-exist-exception.md new file mode 100644 index 000000000..4f95e6354 --- /dev/null +++ b/content/en/docs/2024.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 '' service does not exist." +``` + +where: +- `` will be the name of the service in Service Fabric Explorer (e.g. fabric:/Core/Services/DataStorage). + +#### How to fix + +Ensure the specified service exists. + +## Properties + +### Exception Type + +The type of the exception (i.e. `ServiceDoesNotExistException`) + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: +- `` will be replaced with the name of the service. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Tenant + +The tenant specified on the [Scope][] provided. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### System + +The system specified on the [Scope][] provided. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### Service Name + +The name of the service that does not exist. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### 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 + +* [Scope][] +* [String][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +- Data Storage + - [Create Collection][] + - [Delete Collection][] + - [Delete Data With Key][] + - [Read Data With Key][] + - [Write Data With Key][] + +### External Documentation + +None + +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} +[Delete Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc">}} +[Delete Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.MainDoc">}} +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Scope]: {{< url path="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Core Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.MainDoc">}} +[Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/services/service-unavailable-exception.md b/content/en/docs/2024.9/Reference/Exceptions/services/service-unavailable-exception.md new file mode 100644 index 000000000..63b68abc6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/services/service-unavailable-exception.md @@ -0,0 +1,129 @@ +--- +title: "ServiceUnavailableException" +linkTitle: "ServiceUnavailableException" +description: "The exception thrown when a service is unavailable." +--- + +# {{% param title %}} + +

(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 '' service was unavailable." +``` + +where: +- `` will be the name of the service in Service Fabric Explorer (e.g. fabric:/Core/Services/DataStorage). + +#### How to fix + +Ensure the specified service is running and healthy. + +## Properties + +### Exception Type + +The type of the exception (i.e. `ServiceUnavailableException`) + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Message + +The exception message, providing information about the exception that occurred. + +For this exception: +- `` will be replaced with the name of the service. + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Tenant + +The tenant specified on the [Scope][] provided. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### System + +The system specified on the [Scope][] provided. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### Service Name + +The name of the service that is not running or is unhealthy. + +| | | +|-----------|---------------------------| +| Data Type | [String][] | + +### 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 + +* [Scope][] +* [String][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +- Data Storage + - [Create Collection][] + - [Delete Collection][] + - [Delete Data With Key][] + - [Read Data With Key][] + - [Write Data With Key][] + +### External Documentation + +None + +[Create Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.CreateCollection.CreateCollectionBlock.MainDoc">}} +[Delete Collection]: {{< url path = "Cortex.Reference.Blocks.DataStorage.DeleteCollection.DeleteCollectionBlock.MainDoc">}} +[Delete Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.DeleteData.DeleteDataWithKeyBlock.MainDoc">}} +[Read Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.ReadData.ReadDataWithKeyBlock.MainDoc">}} +[Write Data With Key]: {{< url path="Cortex.Reference.Blocks.DataStorage.WriteData.WriteDataWithKeyBlock.MainDoc">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Scope]: {{< url path="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Core Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.MainDoc">}} +[Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/ssh/_index.md b/content/en/docs/2024.9/Reference/Exceptions/ssh/_index.md new file mode 100644 index 000000000..d4b3a7953 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/ssh/_index.md @@ -0,0 +1,5 @@ +--- +title: "Ssh" +linkTitle: "Ssh" +description: "Exceptions related to Ssh" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-client-exception.md b/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-client-exception.md new file mode 100644 index 000000000..e8765b609 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-client-exception.md @@ -0,0 +1,106 @@ +--- +title: "SshClientException" +linkTitle: "SshClientException" +description: "The exception thrown when an SSH Client (e.g. Execute Ssh Command Block) is incorrectly configured." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Ssh.SshClientException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an SSH Client (e.g. [Execute Ssh Command Block][]) is incorrectly configured. + +There are multiple reasons that this exception can be thrown: + +* [Host Disconnected][SshSessionDetails.Host] +* [Invalid Configuration Settings][ConfigurationSettings] +* [Invalid Connection][SshSessionDetails] + +## Reasons + +### Host Disconnected {#sshsessiondetailshost} + +The connection to the host server has been lost, so the session has closed. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The 'Host' \"\" has closed the session. Any subsequent commands run on the session will result in a new one being created. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][SshSessionDetails Host] property provided in the session details; see [SshSessionDetails][SshSessionDetails DataType] for more information + +#### How to fix + +Ensure that the connection to the host server is functional, and that no commands to close the old session have been executed (e.g. `exit`). + +### Invalid Configuration Settings {#configurationsettings} + +The [Configuration Settings][SshSessionDetailsConfigurationSettings] provided were invalid (e.g. an invalid setting key was provided, a setting was provided an invalid value, etc). + +#### Message Format + +The format of the exception message is as follows: + +```json +"'Configuration Settings' contains one or more invalid settings. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Fix the errors which caused this exception to be thrown, which are seen in the `InvalidSettings` property of this exception. + +### Invalid Connection {#sshsessiondetails} + +The [Ssh Session Details][SshSessionDetailsSshSessionDetails] provided is invalid (e.g. an invalid hostname was provided, an invalid port was provided, the connection timed out, etc). + +#### Message Format + +The format of the exception message is as follows: + +```json +"A connection could not be established between the server where the Cortex Execution Service is running (\"\") and the host. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the value of the [Host][SshSessionDetails Host] property provided in the session details; see [SshSessionDetails][SshSessionDetails DataType] for more information + +#### How to fix + +Ensure that the [Ssh Session Details][SshSessionDetailsSshSessionDetails] provided are valid; see [SshSessionDetails][SshSessionDetails DataType] for more information. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[SshSessionDetails]: {{}} +[SshSessionDetails.Host]: {{}} +[ConfigurationSettings]: {{}} + +[SshSessionDetails DataType]: {{}} +[SshSessionDetails Host]: {{}} + +[IPWorksSSHClientErrors]: {{}} + +[Execute Ssh Command Block]: {{}} +[SshSessionDetailsConfigurationSettings]: {{}} +[SshSessionDetailsSshSessionDetails]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-response-exception.md b/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-response-exception.md new file mode 100644 index 000000000..c965e3d3c --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/ssh/ssh-response-exception.md @@ -0,0 +1,55 @@ +--- +title: "SshResponseException" +linkTitle: "SshResponseException" +description: "The exception thrown when an error occurs from the SSH response." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Ssh.SshResponseException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when an error occurs from the SSH response. + +There is a single reason that this exception can be thrown: + +* [Invalid TerminalPrompt or Short Timeout][SshSessionDetails.TerminalPrompt] + +## Reasons + +### Invalid TerminalPrompt or Short Timeout {#sshsessiondetailsterminalprompt} + +The [TerminalPrompt][SshSessionDetails TerminalPrompt] was not found in the response, or the timeout provided was too short to allow for the response to be returned. + +#### Message Format + +The format of the exception message is as follows: + +```json +"The execution has timed-out because either the 'TerminalPrompt' was not found in the response or the timeout was too short to allow for the response to be returned. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure that the [TerminalPrompt][SshSessionDetails TerminalPrompt] in the [Ssh Session Details][SshSessionDetails] provided matches the terminal prompt on the host and that the `Timeout` in the [Configuration Settings][SshSessionDetailsConfigurationSettings] provided is long enough for a response to be returned. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[SshSessionDetails.TerminalPrompt]: {{}} + +[SshSessionDetails]: {{}} +[SshSessionDetailsConfigurationSettings]: {{}} +[SshSessionDetails TerminalPrompt]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/tasks/_index.md b/content/en/docs/2024.9/Reference/Exceptions/tasks/_index.md new file mode 100644 index 000000000..476e38a46 --- /dev/null +++ b/content/en/docs/2024.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/2024.9/Reference/Exceptions/tasks/aggregate-task-exception.md b/content/en/docs/2024.9/Reference/Exceptions/tasks/aggregate-task-exception.md new file mode 100644 index 000000000..72576c963 --- /dev/null +++ b/content/en/docs/2024.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][IDictionary] +* [Int32][] +* [String][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +* [Wait For All Tasks][] + +### External Documentation + +None + +[Message]: {{< ref "#message" >}} + +[TaskExceptions Property]: {{< ref "#taskexceptions" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} +[Waiting for a Task that has thrown an exception]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.GetSuccessfulResults" >}} + +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[FlowException]: {{< url path="Cortex.Reference.Exceptions.Flows.FlowException.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.WhatIsAnException.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/telnet/_index.md b/content/en/docs/2024.9/Reference/Exceptions/telnet/_index.md new file mode 100644 index 000000000..d48c02c62 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/telnet/_index.md @@ -0,0 +1,5 @@ +--- +title: "Telnet" +linkTitle: "Telnet" +description: "Exceptions related to Telnet" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-client-exception.md b/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-client-exception.md new file mode 100644 index 000000000..4dafe3cc0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-client-exception.md @@ -0,0 +1,203 @@ +--- +title: "TelnetClientException" +linkTitle: "TelnetClientException" +description: "The exception thrown when a Telnet Client (e.g. Execute Telnet Command Block) is incorrectly configured." +--- + +# {{% param title %}} + +

(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 (\"\") and the host. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the server where the {{% ctx %}} Execution Service is running on. + +#### How to Fix + +Provide a valid [Host][] in the [TelnetSessionDetails][] and ensure that the telnet server is up and running without issues. + +*** + +### Invalid Port {#101} + +A [Category][] of `TelnetSessionDetails` and an [ErrorCode][] of `101` indicates that the [Port][] 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 (\"\") and the host. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the server where the {{% ctx %}} Execution Service is running on. + +#### How to Fix + +Provide a valid [Port][] between the [Int32][] values 1 and 65535 in the [TelnetSessionDetails][] and ensure that the telnet server is up and running without issues and configured to accept connections through the specified port. + +*** + +### Invalid Terminal Prompt {#102} + +A [Category][] of `TelnetSessionDetails`and an [ErrorCode][] of `102` indicates that the [TerminalPrompt][] provided in the [TelnetSessionDetails][] could not be matched in the response returned from the [Host][]. + +#### Message Format + +```json +"The execution has timed-out because either the 'TerminalPrompt' was not found in the response or the timeout was too short to allow for the response to be returned. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to Fix + +Provide a [TerminalPrompt][] regex that will match the terminal prompt returned in the response from the [Host][] and ensure that the [Inactivity Timeout][] is long enough for the response to be returned. + +*** + +### Invalid Configuration Settings {#200} + +A [Category][] of `ConfigurationSettings`and an [ErrorCode][] of `200` indicates that one or more settings in [ConfigurationSettings] are invalid. + +#### Message Format + +```json +"'Configuration Settings' contains one or more invalid settings. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to Fix + +Ensure each setting within [ConfigurationSettings] has the correct name and value. + +*** + +## Properties + +### Exception Type + +The type of the exception (i.e. `TelnetClientException`) + +| | | +|-----------|------------| +| 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 `TelnetClientException` there are the following categories: + +- `TelnetSessionDetails` +- `ConfigurationSettings` + +| | | +|-----------|------------| +| 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 `TelnetClientException` there are the following error codes: + +- [100][Invalid Host] - indicates that the [Host][] provided in the [TelnetSessionDetails][] is invalid. +- [101][Invalid Port] - indicates that the [Port][] provided in the [TelnetSessionDetails][] is invalid. +- [102][Invalid Terminal Prompt] - indicates that the [TerminalPrompt][] provided in the [TelnetSessionDetails][] could not be matched in the response returned from the [Host][]. +- [200][Invalid Configuration Settings] - indicates that one or more settings in [ConfigurationSettings] are invalid. + +| | | +|-----------|---------------------------| +| Data Type | [TelnetClientErrorCode][] | + + +### Help Link + +The URL for the relevant section of this exception's help page. + +| | | +|-----------|------------| +| Data Type | [String][] | + +## Remarks + +### Known Limitations + +None + +### Related Data Types + +- [TelnetSessionDetails][] +- [TelnetClientErrorCode][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Exceptions][] + +### Related Blocks + +- [Execute Telnet Command] + +### External Documentation + +- IPWorks Telnet Error Codes: [IpWorksTelnetErrorCodes] + +[Invalid Configuration Settings]: {{< ref "#200">}} +[Invalid Terminal Prompt]: {{< ref "#102">}} +[Invalid Port]: {{< ref "#101">}} +[Invalid Host]: {{< ref "#100">}} + +[Category]: {{< ref "#category" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[ErrorCode]: {{< ref "#error-code" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[Port]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Port" >}} +[TelnetSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.MainDoc" >}} +[TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.TerminalPrompt" >}} +[ConfigurationSettings]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.ConfigurationSettings" >}} +[Execute Telnet Command]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.MainDoc" >}} +[TelnetClientErrorCode]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetClientErrorCode.MainDoc" >}} + +[Inactivity Timeout]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.InactivityTimeout" >}} + +[IpWorksTelnetErrorCodes]: {{< url path="IPWorks.TelnetErrors" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-server-exception.md b/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-server-exception.md new file mode 100644 index 000000000..30c8a5d17 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/telnet/telnet-server-exception.md @@ -0,0 +1,132 @@ +--- +title: "TelnetServerException" +linkTitle: "TelnetServerException" +description: "The exception thrown when an issue occurs on the Telnet Server." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Telnet.TelnetServerException)

+ +## Description + +The exception thrown when an issue occurs on the Telnet Server. + +There is one reason that this exception can be thrown: + +- [Host Disconnected][HostDisconnected] + +## Reasons + +### Host Disconnected {#100} + +A [Category][] of `TelnetSession` and an [ErrorCode][] of `100` indicates that the [Host][] provided has disconnected from the session without using [CloseSession]. The [Response] received up to the point the [Host][] disconnected the session will be returned. + +#### Message Format + +```json +"The 'Host' \"\" has closed the session. Any subsequent commands run on the session will result in a new one being created. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +- `` is the address of the telnet server that the telnet session was opened with. + +#### How to Fix + +Check the [Host] telnet server is running. If it is running please check you haven't sent it an `exit` command, as this will cause the exception. If the exception persists please troubleshoot common reasons for telnet servers disconnecting. + +*** + +## Properties + +### Exception Type + +The type of the exception (i.e. `TelnetServerException`) + +| | | +|-----------|------------| +| 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. + +For `TelnetServerException` there is the following category: + +- `TelnetSession` + +| | | +|-----------|------------| +| Data Type | [String][] | + +### Error Code + +The error code for the exception, which is used to indicate the reason that the exception occurred. + +For `EmailSessionException` there is the following error code: + +- [100][HostDisconnected] - indicates that the [Host][] provided has disconnected from the session without using [CloseSession]. + +| | | +|-----------|---------------------------| +| Data Type | [TelnetServerErrorCode][] | + +### 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 + +- [TelnetSessionDetails][] +- [TelnetServerErrorCode][] +- [String][] + +### Related Concepts + +- [Exceptions][] + +### Related Blocks + +- [Execute Telnet Command][] + +### External Documentation + +None + +[HostDisconnected]: {{< ref "#100">}} +[ErrorCode]: {{< ref "#error-code" >}} +[Category]: {{< ref "#category" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[Response]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.Response" >}} + +[CloseSession]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.CloseSession" >}} +[TelnetSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.MainDoc" >}} +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} +[Execute Telnet Command]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.MainDoc" >}} +[TelnetServerErrorCode]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetServerErrorCode.MainDoc" >}} + +[IpWorksTelnetErrorCodes]: {{< url path="IPWorks.TelnetErrors" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/_index.md b/content/en/docs/2024.9/Reference/Exceptions/text/_index.md new file mode 100644 index 000000000..a12ed413a --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Text" +linkTitle: "Text" +description: "Exceptions related to Text" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/encoding/_index.md b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/_index.md new file mode 100644 index 000000000..4f07ce9ca --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/_index.md @@ -0,0 +1,5 @@ +--- +title: "Encoding" +linkTitle: "Encoding" +description: "Exceptions related to issues with encoding or decoding text" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/encoding/format-exception.md b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/format-exception.md new file mode 100644 index 000000000..0fd5824d2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/format-exception.md @@ -0,0 +1,87 @@ +--- +title: "FormatException" +linkTitle: "FormatException" +description: "The exception thrown when a format template string is invalid." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Text.FormatException)

+{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a format template string is invalid. + +## Reasons + +### Invalid format template + +The [format template][Format Templates] provided could not be parsed. + +#### Message Format + +The format of the message can be one of the following: + +```json +"The largest Format Parameter in '' is , therefore, '' must contain at least items, but only contains . +Text: + +Values: + +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"'' contains at least one Format Parameter larger than {0}, therefore, it cannot be formatted. +Text: + +Please click the HelpLink for more information on how to fix this." +``` + +or + +```json +"'' contains negative Format Parameter(s), therefore, it cannot be formatted. +Text: + +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the format template provided for the block which threw this exception; see [Format Text With Value][Format Text With Value Format Template] or [Format Text With Values][Format Text With Values Format Template] for more information. +* `` is the value of the format template provided; see [Format Text With Value][Format Text With Value Format Template] or [Format Text With Values][Format Text With Values Format Template] for more information. +* `` is the value of the largest unique format specifier provided (i.e. if the format template is `"{0} {2} {1} {3}`, this will be `3`). +* `` is the number of values expected to be provided (i.e. if the format template is `"{0} {2} {1} {3}`, this will be `4`). +* `` is the property containing the values provided to insert into the format template. +* `` is the list of values provided to insert into the format template. + +#### How to fix + +* Ensure that the list of values provided contains at least `` values (e.g. for a format template of `"{0} {1} {2} {3} {4}"`, there should be at least `5` values provided). +* Ensure that the format template provided does not have more than 1 format parameter when using the [Format Text With Value][] block. +* Ensure that the format template provided does not contain any negative format specifiers (e.g. `{-1}`, `{-5}`, `{-1000}`, etc). + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[Format Text With Value]: {{}} +[Format Text With Value Format Template]: {{}} +[Format Text With Values]: {{}} +[Format Text With Values Format Template]: {{}} + +[Working With Text Formatting]: {{}} +[Format Specifiers]: {{}} +[Format Templates]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/encoding/text-decoding-exception.md b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/text-decoding-exception.md new file mode 100644 index 000000000..0a7d687d9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/encoding/text-decoding-exception.md @@ -0,0 +1,165 @@ +--- +title: "TextDecodingException" +linkTitle: "TextDecodingException" +description: "The exception thrown when an error occurs while decoding text." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Text.Encoding.TextDecodingException)

+ +## Description + +The exception thrown when an error occurs while decoding text. + +There are multiple reasons that this exception can be thrown: + +- [Invalid Base64 Character][InvalidBase64Character] +- [Odd number of characters using Hex][OddHexCharacters] +- [Invalid Base64Url Character][InvalidBase64UrlCharacter] + +## Reasons + +### Invalid Base64 character {#100} + +A [Category][] of `Base64` and an [Error Code][] of `100` indicates that the text provided contains one or more characters that are invalid in [Base64][] encoded text. + +#### Message Format + +```json +"An error occurred during decoding due to one or more invalid characters being present. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a [String][] containing only valid characters (e.g. `A–Z`, `a–z`, `0–9`, `+`, `/` and `=`). + +### Odd number of characters using Hex {#300} + +A [Category][] of `Hex` and an [Error Code][] of `300` indicates that the provided text contains an odd number of characters, which is invalid for [Hex][] encoded text. + +#### Message Format + +```json +"An error occurred during decoding due to an odd number of characters being present. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a [String][] containing an even number of characters. + +### Invalid Base64Url character {#600} + +A [Category][] of `Base64Url` and an [Error Code][] of `600` indicates that the text provided contains one or more characters that are invalid in [Base64Url][] encoded text. + +#### Message Format + +```json +"An error occurred during decoding due to one or more invalid characters being present. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Provide a [String][] containing only valid characters (e.g. `A–Z`, `a–z`, `0–9`, `+`, `/` and `=`). + +## Properties + +### Exception Type + +The type of the exception (i.e. `TextDecodingException`) + +| | | +|-----------|------------| +| 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 `TextDecodingException` there are the following categories: + +- `Base64` +- `Hex` +- `Base64Url` + +| | | +|-----------|------------| +| 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 `TextEncodingException` there are the following error codes: + +- [100][InvalidBase64Character] - indicates that the Base64 encoded text provided contains one or more invalid characters +- [300][OddHexCharacters] - indicates that the Hex encoded text provided contains an odd number of characters, which is invalid +- [600][InvalidBase64UrlCharacter] - indicates that the Base64Url encoded text provided contains one or more invalid characters + +| | | +|-----------|---------------------------| +| Data Type | [TextDecodingErrorCode][] | + +### 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][] +* [TextDecodingErrorCode][] + +### Related Concepts + +* [Exceptions][] +* [Working with Text][WorkingWithText] + +### Related Blocks + +* [Decode Text][] + +### External Documentation + +None + +[Decode Text]: {{< url path="Cortex.Reference.Blocks.Text.DecodeText.DecodeText.MainDoc" >}} +[InvalidBase64Character]: {{< ref "#100">}} +[OddHexCharacters]: {{< ref "#300">}} +[InvalidBase64UrlCharacter]: {{< ref "#600">}} +[Category]: {{< ref "#category">}} +[Error Code]: {{< ref "#error-code">}} + +[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" >}} + +[WorkingWithText]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[TextDecodingErrorCode]: {{< url path="Cortex.Reference.DataTypes.Text.TextDecodingErrorCode.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/regex/_index.md b/content/en/docs/2024.9/Reference/Exceptions/text/regex/_index.md new file mode 100644 index 000000000..a01477428 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/regex/_index.md @@ -0,0 +1,5 @@ +--- +title: "Regex" +linkTitle: "Regex" +description: "Exceptions related to issues with Regex" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/text/regex/regex-parsing-failed-exception.md b/content/en/docs/2024.9/Reference/Exceptions/text/regex/regex-parsing-failed-exception.md new file mode 100644 index 000000000..fed6fcd85 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/text/regex/regex-parsing-failed-exception.md @@ -0,0 +1,74 @@ +--- +title: "RegexParsingFailedException" +linkTitle: "RegexParsingFailedException" +description: "The exception thrown when a property is provided with invalid regex syntax." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Text.Regex.RegexParsingFailedException)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Description + +The exception thrown when a property is provided with invalid [regex syntax][regex]. + +## Reasons + +### Single regex pattern failed to parse + +A regex pattern in the property value failed to parse successfully due to invalid [regex syntax][regex] (e.g. `"*"`). + +#### Message Format + +The format of the exception message is as follows: + +```json +"'' contains regex pattern \"\" which could not be parsed successfully. Please see the 'RegexParseExceptions' property for details on why the regex failed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the regex pattern that failed to parse. +* `` is the pattern with the invalid regex syntax. + +#### How to fix + +Provide valid [regex syntax][regex], for the regex pattern seen in the `RegexParseExceptions` property. + +### Multiple regex patterns failed to parse + +Multiple regex patterns in the property value failed to parse successfully due to invalid [regex syntax][regex] (e.g. `"*"`). + +#### Message Format + +The format of the exception message is as follows: + +```json +"'' contains one or more regex patterns which could not be parsed succesfully. Please see the 'RegexParseExceptions' property for details on why each regex failed. +Please click the HelpLink for more information on how to fix this." +``` + +where: + +* `` is the name of the property containing the regex patterns that failed to parse. + +#### How to fix + +Provide valid [regex syntax][regex], for each regex pattern seen in the `RegexParseExceptions` property. + +## Remarks + +### Known Limitations + +None + +## See Also + +### External Documentation + +None + +[regex]: {{}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/Exceptions/wireless/_index.md b/content/en/docs/2024.9/Reference/Exceptions/wireless/_index.md new file mode 100644 index 000000000..7bb712150 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/wireless/_index.md @@ -0,0 +1,5 @@ +--- +title: "Wireless" +linkTitle: "Wireless" +description: "Exceptions related to issues with wireless blocks" +--- diff --git a/content/en/docs/2024.9/Reference/Exceptions/wireless/wireless-receiver-block-not-found-exception.md b/content/en/docs/2024.9/Reference/Exceptions/wireless/wireless-receiver-block-not-found-exception.md new file mode 100644 index 000000000..4158dbda7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Exceptions/wireless/wireless-receiver-block-not-found-exception.md @@ -0,0 +1,142 @@ +--- +title: "WirelessReceiverBlockNotFoundException" +linkTitle: "WirelessReceiverBlockNotFoundException" +description: "The exception thrown when a wireless receiver block could not be found." +--- + +# {{% param title %}} + +

(Cortex.Exceptions.Wireless.WirelessReceiverBlockNotFoundException)

+ +## Description + +The exception thrown when a [Wireless Receiver][Wireless Receiver Block] block could not be found. + +There are multiple reasons that this exception can be thrown: + +- [Wireless Receiver Block Not Found][WirelessReceiverExceptionBlockNotFound] +- [Wireless Receiver Property Empty][WirelessReceiverExceptionPropertyEmpty] + +## Reasons + +### Wireless Receiver Block Not Found {#100} + +A [Category][] of `NotFound` and an [Error Code][] of `100` indicates that the selected [Wireless Receiver][Wireless Receiver Block] block was deleted or does not exist. + +#### Message Format + +```json +"The 'Wireless Receiver Block' provided could not be found. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure the correct [Wireless Receiver][Wireless Receiver Block] block is selected. + +### Wireless Receiver Property Empty {#101} + +A [Category][] of `NotFound` and an [Error Code][] of `101` indicates that a [Wireless Receiver][Wireless Receiver Block] block has not been selected. + +#### Message Format + +```json +"'Wireless Receiver Block' is empty; it must be provided a value. +Please click the HelpLink for more information on how to fix this." +``` + +#### How to fix + +Ensure a [Wireless Receiver][Wireless Receiver Block] block is selected. + +## Properties + +### Exception Type + +The type of the exception (i.e. `WirelessReceiverBlockNotFoundException`) + +| | | +|-----------|------------| +| 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 `WirelessReceiverBlockNotFoundException` there are the following categories: + +- `NotFound` + +| | | +|-----------|------------| +| 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 `WirelessReceiverBlockNotFoundException` there are the following error codes: + +- [100][WirelessReceiverBlockNotFound] - indicates that the [Wireless Receiver][Wireless Receiver Block] block could not be found +- [101][WirelessReceiverPropertyEmpty] - indicates that the [Wireless Receiver Block][Wireless Receiver Block Property] property was empty + +| | | +|-----------|---------------------------| +| Data Type | [WirelessReceiverNotFoundErrorCode][WirelessReceiverNotFoundErrorCode] | + +### 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][] +* [WirelessReceiverNotFoundErrorCode][] + +### Related Concepts + +* [Exceptions][] + +### Related Blocks + +* [Wireless Sender Block][] + +### External Documentation + +None + +[Category]: {{< ref "#category">}} +[Error Code]: {{< ref "#error-code">}} +[WirelessReceiverBlockNotFound]: {{< ref "#100">}} +[WirelessReceiverPropertyEmpty]: {{< ref "#101">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[Wireless Sender Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.MainDoc" >}} +[Wireless Receiver Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessReceiver.WirelessReceiver.MainDoc" >}} +[WirelessReceiverExceptionBlockNotFound]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.BlockNotFound" >}} +[WirelessReceiverExceptionPropertyEmpty]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.PropertyEmpty" >}} +[WirelessReceiverNotFoundErrorCode]: {{< url path="Cortex.Reference.DataTypes.Wireless.WirelessReceiverBlockNotFoundErrorCode.MainDoc" >}} +[Wireless Receiver Block Property]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.WirelessReceiverProperty" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/0-9.md b/content/en/docs/2024.9/Reference/Glossary/0-9.md new file mode 100644 index 000000000..c09f7e658 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/0-9.md @@ -0,0 +1,52 @@ +--- +title: "0-9" +linkTitle: "0-9" +description: "Terms, words and phrases beginning with the numbers 0 through 9." +weight: 100 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the numbers 0 through 9. + +## 0 + +### 0 Based + +See [Zero Based][]. + +## 1 + +### 16-bit + +16-bit refers to a measurement of units of memory or data that are 16 bits in size. + +## 2 + +## 3 + +### 32-bit + +32-bit refers to a measurement of units of memory or data that are 32 bits in size. + +### 3rd-Party Systems + +3rd-party systems refer to systems, services or applications that are not developed by {{% ctx %}}. + +## 4 + +## 5 + +## 6 + +### 64-bit + +64-bit refers to a measurement of units of memory or data that are 64 bits in size. + +## 7 + +## 8 + +## 9 + +[Zero Based]: {{< url path="Cortex.Reference.Glossary.U-Z.ZeroBased" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/_index.md b/content/en/docs/2024.9/Reference/Glossary/_index.md new file mode 100644 index 000000000..cf30bc118 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/_index.md @@ -0,0 +1,6 @@ +--- +title: "Glossary" +linkTitle: "Glossary" +description: "Explanation of terms, words and phrases used throughout the {{% ctx %}} documentation." +weight: 1000 +--- diff --git a/content/en/docs/2024.9/Reference/Glossary/a-e.md b/content/en/docs/2024.9/Reference/Glossary/a-e.md new file mode 100644 index 000000000..e644a01c5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/a-e.md @@ -0,0 +1,447 @@ +--- +title: "A-E" +linkTitle: "A-E" +description: "Terms, words and phrases beginning with the letters A through E." +weight: 10 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the letters A through E. + +## A + +### API + +An API (Application Programming Interface) is a set of functions that allows applications to access data from and interact with external systems, services or applications. + +### Autogeneration + +Autogeneration, is the process in which something is created automatically for use within a process. + +### Automate + +The application of [automation][]. + +### Automation + +Automation is a term for techniques, methods, systems or technologies that reduce human intervention in [tasks][] and [processes][]. + +### AWS Lambda + +AWS Lambda is an event driven serverless solution from AWS. Instead of deploying and maintaining servers, cloud infrastructure is used to run applications. + +### Azure Functions + +Azure Functions is an event driven serverless solution from Microsoft. Instead of deploying and maintaining servers, cloud infrastructure is used to run applications. + +## B + +### BCC + +Blind Carbon Copy (BCC) is a way of sending copies of an email to other people. Unlike [CC][] recipients, the other recipients of the email will not be able to see who recieved the email via BCC. + +### Bit + +A bit is the most basic unit of information in computing, and represents a logical state with one of two possible values; most commonly represented as 1 or 0. + +See [Wikipedia][Bit (Wikipedia)] for more information. + +### Block + +Blocks (or [functional blocks][]) expose the logic and actions that the [{{% ctx %}}][CORTEX] [platform][] is able to execute for the [flow developers][]; alongside [flows][Flow] they are one of the main components used to define how to automate [tasks][] and [processes][]. + +For more detailed information about blocks, see [Fundamentals > Blocks][]. + +For a complete list of available blocks, see [Reference > Blocks][]. + +### Block Property + +[Blocks][Block] have block properties (or [properties][]) that allow the [flow developers][] to configure how the block should behave; e.g. a block to send emails would have properties for specifying things like the sender, recipients, summary, body, attachments etc. + +For more detailed information about configuring blocks using block properties, see [Fundamentals > Block Properties][]. + +### Boolean + +A [data type][] that represents a logical value of `true` or `false`. + +For more detailed information about the Boolean data type, see [Data Types > Boolean][]. + +### Byte + +A byte is a unit of information in computing that most commonly consists of eight [bits][Bit]. + +See [Wikipedia][Byte (Wikipedia)] for more information. + +## C + +### C\# + +C# (pronounced "see sharp") is a [programming language][] developed by Microsoft. + +It is natively supported by the [{{% ctx %}}][CORTEX] [platform][] for using simple [expressions][Expression] (i.e. `1 + 1`) and more complex [code][] (i.e. `DateTime.Now.AddDays(1)`) within [flows][Flow]. + +C# expressions and code can be entered as the values for [Fundamentals > Block Properties][Block Property] using the [Expression Editor][]. + +See the official [C# documentation][] for more information about C#. + +### camelCase + +camelCase is a typographical convention in which phrases are written without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word starting with a lowercase letter. E.g. "iPhone" and "eBay". + +camelCase is often used as a naming convention in programming languages such as [C#][]. + +See also [PascalCase][]. + +### Case-insensitive + +If something is case-insensitive, it means it ignores differences in case (i.e. `CASE` is considered equal to `case`). + +### Case-sensitive + +If something is case-sensitive, it means it considers differences in case (i.e. `CASE` is considered not equal to `case`). + +### Cast + +The process of explicitly converting one [data type][] to another. + +See [Casting and type conversions (C# Programming Guide)][] for a detailed technical explanation of casting in [C#][], the [programming language][] natively supported by the [{{% ctx %}}][CORTEX] [platform][] for writing simple [expressions][Expression] and more complex [code][]. + +Also see [Explicit Cast][] for more information. + +### CC + +Carbon Copy (CC) is a way of sending copies of an email to other people. The other recipients of the email will be able to see who recieved the email via CC. + +### CI/CD + +CI/CD is a software development practice and is broken down into the following concepts: + +- [Continuous Integration][] +- [Continuous Delivery][] +- [Continuous Deployment][] + +### Char + +A [data type][] that represents a character or letter. + +For more detailed information about the Char data type, see [Data Types > Char][]. + +### Cloud + +A global network of servers which are linked together and operate as a single ecosystem. + +Examples of publicly available Cloud providers include: + +* Amazon AWS +* Google Cloud Platform +* Microsoft Azure + +### Cloud Service Provider + +A cloud service provider is a third-party company offering a cloud-based platform, infrastructure, application, or storage services. + +### Code + +A set of instructions in a computer program. + +### Concurrent + +At the same time. + +### Continuous Integration + +Continuous Integration is a software development practice where developers frequently: + +- Integrate their local changes with source code from the main branch +- Use automated testing to ensure that their changes work as expected +- Merge their changes into the main branch, if no issues were found + +### Continuous Delivery + +Continuous Delivery is a software development practice where: + +- Changes to the main branch are detected +- The main branch is packaged into deployment artefacts +- Deployment artefacts are made available + +### Continuous Deployment + +Continuous Deployment is a software development practice which extends [Continuous Delivery][] by automatically deploying the generated artefacts. + +### Convert + +To change something into a different form. E.g. Change some [text][] from [lowercase][] to [UPPERCASE][]. + +### CORS + +Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from a domain outside of the domain from which the first resource was served. + +### {{% ctx %}} + +The name of the new and current generation of the {{% ctx %}} [automation][] [platform][]. + +### {{% ctx %}} Gateway + +The centralised web-based [portal][] for accessing all user applications and tooling in the [{{% ctx %}}][CORTEX] [platform][]. + +### {{% ctx %}} Studio + +The web-based integrated development environment ([IDE][]) for creating, editing, [debugging][], testing and managing [flows][Flow] that define the logic and actions required to capture and automate a [task][tasks] or [process][Processes]. + +For more detailed information about {{% ctx %}} Studio, see [Guides > {{% ctx %}} Studio][Guides > CORTEX Studio]. + +### Culture + +Describes a set of rules for data that differs between different cultures; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and text comparisons. + +For more detailed information about Culture, see [Working With > Culture][]. + +### Culture identifier + +A culture identifier is a standard international numeric abbreviation and has the components necessary to uniquely identify one of the operating system's installed cultures. + +For more detailed information about Culture, see [Working With > Culture][]. + +### Culture-insensitive + +If something is culture-insensitive, it means that it does not get affected by culture related changes to the operating system, such as language and regional settings. + +### Culture-sensitive + +If something is culture-sensitive, it means that it does get affected by culture related changes to the operating system, such as language and regional settings. + +### Current Culture + +The current culture used by the executing thread; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. + +For more detailed information about Culture, see [Working With > Current Culture][]. + +### CRL + +Certificate Revocation List (CRL) is a list of certificates that have been revoked by the issuing certificate authority prior to their actual/assigned expiration date. It is essentially a list of certificates that should no longer be trusted. + +## D + +### Data Type + +A data type (or [type][]) defines the type of data or values that a [block property][] can accept. + +For more detailed information about data types, see [Fundamentals > Data Types][]. + +For a complete list of available data types, see [Reference > Data Types][]. + +### Debug + +The ability for [flow developers][] to execute and interact with a [flow][] step-by-step from within [{{% ctx %}} Studio][CORTEX Studio], so that they are able to identify and remove [errors][] in the [flow's][flow] logic and actions. + +For more detailed information about debugging in {{% ctx %}} Studio, see [{{% ctx %}} Studio > Debugging][CORTEX Studio > Debugging]. + +### Default Value + +The default that is assigned as the value of a [block property][] when a new [block][] is added to a [flow][]. + +### Developer + +A developer is an individual that builds and creates software and applications. + +### Dictionary + +A [data type][] that represents an unordered collection of key-item pairs, where each pair consists of a unique key and its associated item. Dictionaries are optimised for fast lookup of items using their key. + +For more detailed information about the Dictionary data type, see [Data Types > Dictionary<TKey, TItem>][]. + +### DLL + +DLL files are binary files that can contain executable code and resources. + +### Drag-and-Drop + +Functionality that allows a user to select an object and move it to another location. + +### DotNet + +.NET (DotNet) is an open-source, computer software framework for Windows, Linux, and macOS operating systems developed by Microsoft. + +### Double + +A [data type][] that represents a fractional, or very large or small number from `-1.79769313486232e+308` through `1.79769313486232e+308`. + +For more detailed information about the Double data type, see [Data Types > Double][]. + +### dynamic + +A [data type][] that indicates that any data type can be used. + +For more detailed information about the dynamic data type, see [Data Types > dynamic][]. + +## E + +### Empty + +Empty indicates that a [data type][] has been [initialised][] and has a [non-null][] value, but the value does not contain any data. E.g. a [string][] that contains no characters `""`, or a [list][] that contains no items `[]`. + +Empty is not the same as [null][]. + +### Error + +Something which is inaccurate or incorrect; a mistake. + +### Example + +An example is intended to show [flow developers][] how something works. Examples can be found near the top of every [block's][block] help page. See [examples][] for the [Add Text At Beginning][] block. + +### Exception + +An exception represents [errors][] that occur during the [execution][] of a [flow][]. + +Exceptions are [data types][Data Type] that can be reasoned with during the execution of a flow, in order to handle errors during the [automation][] of a [task][tasks] or [process][Processes]. + +For more detailed information about exceptions, see [Fundamentals > Exceptions][]. + +For a complete list of available [blocks][block] that can be used to handle exceptions, see [Blocks > Exception Blocks][]. + +For a complete list of exceptions, see [Reference > Exceptions][]. + +### Execution + +When a [request][] to start a [flow][] is received by the [{{% ctx %}}][CORTEX] [platform][], an execution is created that represents that instance of the executing flow. + +There can be multiple executions of a flow running [concurrently][concurrent]. + +For more detailed information about executions, see [{{% ctx %}} Studio > Debugging][CORTEX Studio > Debugging]. + +### Explicit Cast + +Sometimes, in order to convert one [data type][] to another, an "explicit cast" [expression][] is required; this is typically needed when information might be lost in the conversion, or when the conversion might not succeed for other reasons. + +An example would be converting a [32-bit][] [integer][] ([Int32][]) to a [16-bit][] [integer][] ([Int16][]): + +```csharp +Int32 ThirtyTwoBitInteger = 100; +Int16 SixteenBitInteger = (Int16)ThirtyTwoBitInteger; +``` + +See [Cast expression (C# Reference)][] for a detailed technical explanation. + +Also see [Cast][] for more information. + +### Expression + +An expression is a combination of [operands][] (i.e. [variables][], [literals][], calls to [methods][] and [properties][PropertiesC#] exposed on [data types][Data Type]) and [operators][] (i.e. =, +, -, *, /) that can be evaluated by the [{{% ctx %}}][CORTEX] [platform][] to a single value. + +Expressions use the syntax of the [C#][] [programming language][]. + +For more detailed information about expressions, see [Fundamentals > Expressions][]. + +### Expression Editor + +The Expression Editor is a web-based text editor that allows [flow developers][] to use either simple [expression][] or more complex [code][] as the value of a [block property][]. + +It is based on the [Monaco Editor][] used by [VS Code][], and includes a rich set of features including: + +* [Syntax Highlighting][] +* [Snippets][] +* [Intellisense][] + +For more detailed information about the Expression Editor, see [{{% ctx %}} Studio > Expression Editor][CORTEX Studio > Expression Editor]. + +[Automate]: {{< ref "#automate" >}} +[Automation]: {{< ref "#automation" >}} +[Bit]: {{< ref "#bit" >}} +[Block]: {{< ref "#block" >}} +[Block Property]: {{< ref "#block-property" >}} +[C#]: {{< ref "#c-1" >}} +[Cast]: {{< ref "#cast" >}} +[CC]: {{< ref "#cc" >}} +[Code]: {{< ref "#code" >}} +[Concurrent]: {{< ref "#concurrent" >}} +[Continuous Integration]: {{< ref "#continuous-integration" >}} +[Continuous Delivery]: {{< ref "#continuous-delivery" >}} +[Continuous Deployment]: {{< ref "#continuous-deployment" >}} +[CORTEX]: {{< ref "#cortex" >}} +[CORTEX Studio]: {{< ref "#cortex-studio" >}} +[Data Type]: {{< ref "#data-type" >}} +[Debugging]: {{< ref "#debug" >}} +[Errors]: {{< ref "#error" >}} +[Execution]: {{< ref "#execution" >}} +[Explicit Cast]: {{< ref "#explicit-cast" >}} +[Expression]: {{< ref "#expression" >}} +[Expression Editor]: {{< ref "#expression-editor" >}} + +[Fundamentals > Blocks]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.MainDoc" >}} +[Fundamentals > Block Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.MainDoc" >}} +[Fundamentals > Data Types]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.MainDoc" >}} + +[Working With > Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.MainDoc" >}} +[Working With > Current Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.CurrentCulture.MainDoc" >}} + +[Reference > Blocks]: {{< url path="Cortex.Reference.Blocks.MainDoc" >}} +[Blocks > Exception Blocks]: {{< url path="Cortex.Reference.Blocks.Exceptions.MainDoc" >}} +[Add Text At Beginning]: {{< url path="Cortex.Reference.Blocks.Text.AddText.AddTextAtBeginning.MainDoc" >}} + +[Examples]: {{< url path="Cortex.Reference.Blocks.Text.AddText.AddTextAtBeginning.Examples" >}} + +[Reference > Data Types]: {{< url path="Cortex.Reference.DataTypes.MainDoc" >}} +[Data Types > Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[Data Types > Char]: {{< url path="Cortex.Reference.DataTypes.Text.Char.MainDoc" >}} +[Data Types > Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} +[Data Types > dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Data Types > Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[Fundamentals > Exceptions]: {{< url path="Cortex.Reference.Exceptions.MainDoc" >}} + +[Reference > Exceptions]: {{< url path="Cortex.Reference.Exceptions.MainDoc" >}} + +[Flow]: {{< url path="Cortex.Reference.Glossary.F-J.Flow" >}} +[flow developers]: {{< url path="Cortex.Reference.Glossary.F-J.FlowDeveloper" >}} +[Functional Blocks]: {{< url path="Cortex.Reference.Glossary.F-J.FunctionalBlock" >}} +[Initialised]: {{< url path="Cortex.Reference.Glossary.F-J.Initialised" >}} +[Integer]: {{< url path="Cortex.Reference.Glossary.F-J.Integer" >}} +[Int16]: {{< url path="Cortex.Reference.Glossary.F-J.Int16" >}} +[Int32]: {{< url path="Cortex.Reference.Glossary.F-J.Int32" >}} +[Intellisense]: {{< url path="Cortex.Reference.Glossary.F-J.Intellisense" >}} +[IDE]: {{< url path="Cortex.Reference.Glossary.F-J.IDE" >}} +[Literals]: {{< url path="Cortex.Reference.Glossary.K-O.Literal" >}} +[LowerCase]: {{< url path="Cortex.Reference.Glossary.K-O.LowerCase" >}} +[Methods]: {{< url path="Cortex.Reference.Glossary.K-O.Method" >}} +[Non-Null]: {{< url path="Cortex.Reference.Glossary.K-O.NonNull" >}} +[Null]: {{< url path="Cortex.Reference.Glossary.K-O.Null" >}} +[Operands]: {{< url path="Cortex.Reference.Glossary.K-O.Operand" >}} +[Operators]: {{< url path="Cortex.Reference.Glossary.K-O.Operator" >}} +[PascalCase]: {{< url path="Cortex.Reference.Glossary.P-T.PascalCase" >}} +[Platform]: {{< url path="Cortex.Reference.Glossary.P-T.Platform" >}} +[Portal]: {{< url path="Cortex.Reference.Glossary.P-T.Portal" >}} +[Processes]: {{< url path="Cortex.Reference.Glossary.P-T.Process" >}} +[Programming Language]: {{< url path="Cortex.Reference.Glossary.P-T.ProgrammingLanguage" >}} +[Properties]: {{< url path="Cortex.Reference.Glossary.P-T.PropertyBlock" >}} +[PropertiesC#]: {{< url path="Cortex.Reference.Glossary.P-T.PropertyCSharp" >}} +[Request]: {{< url path="Cortex.Reference.Glossary.P-T.Request" >}} +[Snippets]: {{< url path="Cortex.Reference.Glossary.P-T.Snippets" >}} +[Syntax Highlighting]: {{< url path="Cortex.Reference.Glossary.P-T.SyntaxHighlighting" >}} +[tasks]: {{< url path="Cortex.Reference.Glossary.P-T.Task" >}} +[Text]: {{< url path="Cortex.Reference.Glossary.P-T.Text" >}} +[Type]: {{< url path="Cortex.Reference.Glossary.P-T.Type" >}} +[UpperCase]: {{< url path="Cortex.Reference.Glossary.U-Z.UpperCase" >}} +[Variables]: {{< url path="Cortex.Reference.Glossary.U-Z.Variable" >}} +[16-bit]: {{< url path="Cortex.Reference.Glossary.0-9.16Bit" >}} +[32-bit]: {{< url path="Cortex.Reference.Glossary.0-9.32Bit" >}} +[data type]: {{< url path="Cortex.Reference.Glossary.A-E.DataType" >}} + +[Guides > CORTEX Studio]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[CORTEX Studio > Debugging]: {{< url path="Cortex.Guides.Studio.Debugging.MainDoc" >}} +[CORTEX Studio > Expression Editor]: {{< url path="Cortex.Guides.Studio.ExpressionEditor.MainDoc" >}} + +[Fundamentals > Expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.Expressions" >}} + +[Casting and type conversions (C# Programming Guide)]: {{< url path="MSDocs.CSharp.Casting" >}} +[Cast expression (C# Reference)]: {{< url path="MSDocs.CSharp.CastExpression" >}} +[C# documentation]: {{< url path="MSDocs.CSharp.MainDoc" >}} +[List]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.List" >}} +[String]: {{< url path="MSDocs.DotNet.Api.System.String.MainDoc" >}} + +[Monaco Editor]: {{< url path="MSGitHub.MonacoEditor.MainDoc" >}} + +[VS Code]: {{< url path="VisualStudio.Code.MainDoc" >}} + +[Bit (Wikipedia)]: {{< url path="Wikipedia.Bit" >}} +[Byte (Wikipedia)]: {{< url path="Wikipedia.Byte" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/f-j.md b/content/en/docs/2024.9/Reference/Glossary/f-j.md new file mode 100644 index 000000000..c422f93d8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/f-j.md @@ -0,0 +1,267 @@ +--- +title: "F-J" +linkTitle: "F-J" +description: "Terms, words and phrases beginning with the letters F through J." +weight: 20 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the letters F through J. + +## F + +### Fast Track + +A Fast Track release follows a quick release cycle, allowing access to the latest features and functionality of {{% ctx %}}. + +### File + +A file is an object on a computer that stores data. + +Different files can store different types of data (i.e. a text file, `.txt`, stores textual data; an executable file, `.exe` stores data required for executing an application). + +### Flow + +A flow is an object in [{{% ctx %}} Studio][CORTEX Studio] that contains the logic and actions (in the form of [blocks][]) that the [{{% ctx %}}][CORTEX] [platform][] is able to execute for the [flow developers][]. + +For more detailed information about flows, see [Fundamentals > Flows][]. + +### Flow Developer + +A flow developer is a user that has been granted permissions to develop [flows][] in [{{% ctx %}} Studio][CORTEX Studio]. + +For more detailed information about granting permissions to develop [flows][], see [{{% ctx %}} Studio > Authorisation][CORTEX Studio > Authorisation]. + +### Folder + +A folder (or directory) is an object on a computer that contains [files][]. + +Folders can contain different types of file and can also contain other folders. + +### Format Parameter + +See [Text > Format Parameters][]. + +### Format Specifier + +See [Text > Format Specifiers][]. + +### Format Template + +See [Text > Format Templates][]. + +### Functional Block + +See [block][blocks]. + +## G + +### Generics + +Generic means not specific to a particular [data type][]. + +An example of a generic data type is [List<TItem>][] where TItem is a placeholder which indicates it can be initialised with any data type, such as: + +- List<int> and List<string> which are [homogenous][] lists that can only contain integers and strings respectively +- List<object> and List<dynamic> are [heterogenous][] lists that can contain multiple data types + +### Gmail + +Gmail is a free web-based email service provided by Google. + +### GUI + +GUI stands for "Graphical User Interface". It is used to graphically display information and represent user interactions with a system, without the need for typing commands. + +## H + +### Heterogenous + +Consists of dissimilar or diverse constituents. + +Heterogenous collections can contain multiple [data types][data type] (e.g. [List<dynamic>][List<TItem>]). + +Collections that can only contain a single data type are known as [homogenous][]. + +### Homogenous + +Consists of the same or a similar constituents. + +Homogenous collections can only contain a single [data type][] (e.g. [List<int>][List<TItem>]). + +Collections that can contain multiple data types are known as [heterogenous][]. + +### HTML Entity + +An HTML entity is a piece of text that begins with an ampersand (i.e. `&`) and ends with a semicolon (i.e. `;`). Entities are frequently used to display reserved characters (which would otherwise be interpreted as HTML code), and invisible characters (like non-breaking spaces). You can also use them in place of other characters that are difficult to type with a standard keyboard. + +See [WHATWG][WHATWG entity list] for a full list of HTML4 and HTML5 Entities. + +### Human-in-the-Loop + +Human-in-the-Loop or HITL allows people to interact with automated systems and processes, affecting the direction and functionality of the automated systems or process. + +## I + +### IDE + +IDE or Integrated Development Environment is a software application such as [{{% ctx %}} Studio][CORTEX Studio], that allows users to create a program or application. + +In [{{% ctx %}} Studio][CORTEX Studio], the users are called [flow developers][], and the programs are called [flows][]. + +Some common and popular examples of IDE's include: + +* Visual Studio +* VSCode +* Eclipse + +### IMAP + +Internet Messaging Access Protocol (IMAP) in an internet protocol used by email clients to retrieve email messages from a mail server. + +### Immutable + +Unable to be changed. + +### Implicit Cast + +The process of an application converting one [data type][] to another, without requiring an explicit instruction from the developer. + +For one [data type][] to be able to be implicitly cast to another, there should be no data loss during the conversion. + +An example would be converting a [16-Bit][] [integer][] ([Int16][]) to a [32-Bit][] [integer][] ([Int32][]), as the entire range of the 16-bit integer will fit into a 32-bit integer: + +```csharp +Int16 SixteenBitInteger = 100; +Int32 ThirtyTwoBitInteger = SixteenBitInteger; +``` + +See [Explicit Cast][] for an example of where data loss would occur during conversion, and would therefore require an explicit instruction from the developer. + +See [Casting and type conversions (C# Programming Guide)][] for a detailed technical explanation of casting in [C#][], the [programming language][] natively supported by the [{{% ctx %}}][CORTEX] [platform][] for writing simple [expressions][] and more complex [code][]. + +### Index + +An [Index][Collections > Indexes] is used to access an [item][] in a [list][] and relates to the position of the item in the list. + +Indexes are 0 based (e.g. The first item in a list is at index 0, the second item is at index 1, etc.). + +See [Collections > Indexes][]. + +### Intellisense + +IntelliSense is a general term for various [code][] editing features such as code completion and [snippets][]. + +### Initialised + +A [variable][] is initialised when its value has been set for the first time. + +### Input + +Input properties are used to provide values to a [block][blocks]. These properties are used in the block's execution. + +See [Block Properties > Input Properties][]. + +### InputOutput + +InputOutput properties are used to provide values to a [block][blocks]. These properties are used, updated and saved back to a variable during the block's execution. + +See [Block Properties > InputOutput Properties][]. + +### Integer + +A whole number (e.g. `100`). + +### Int16 + +A [data type][] that represents a whole number from `-32,768` through `32,767`. + +For more detailed information about the Int16 data type, see [Int16][]. + +### Int32 + +A [data type][] that represents a whole number from `-2,147,483,648` through `2,147,483,647`. + +For more detailed information about the Int32 data type, see [Int32][]. + +### Int64 + +A [data type][] that represents a whole number from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807`. + +For more detailed information about the Int64 data type, see [Int64][]. + +### Invariant Culture + +A culture associated with the English language, but not with any country or region; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. + +It has a stable and unchanging set of rules that cannot be customized and is unaffected by culture related changes to the operating system. + +See [Working With > Invariant Culture][]. + +### Item + +Each object within a [collection][] is called an [item][]. + +### IT + +IT stands for Information Technology, which is the use of computers to create, process, store, retrieve, and exchange electronic data and information. + +See [Wikipedia][Information Technology (Wikipedia)] for more information. + +## J + +### JSON + +JSON stands for JavaScript Object Notation, and is a format for storing and transporting data between computer applications. + +See [What is JSON][What is Json (W3)] for more information. + +[16-Bit]: {{< url path="Cortex.Reference.Glossary.0-9.16Bit" >}} +[32-Bit]: {{< url path="Cortex.Reference.Glossary.0-9.32Bit" >}} +[blocks]: {{< url path="Cortex.Reference.Glossary.A-E.Block" >}} +[code]: {{< url path="Cortex.Reference.Glossary.A-E.Code" >}} +[CORTEX]: {{< url path="Cortex.Reference.Glossary.A-E.Cortex" >}} +[CORTEX Studio]: {{< url path="Cortex.Reference.Glossary.A-E.CortexStudio" >}} +[C#]: {{< url path="Cortex.Reference.Glossary.A-E.CSharp" >}} +[data type]: {{< url path="Cortex.Reference.Glossary.A-E.DataType" >}} +[Explicit Cast]: {{< url path="Cortex.Reference.Glossary.A-E.ExplicitCast" >}} +[expressions]: {{< url path="Cortex.Reference.Glossary.A-E.Expression" >}} +[files]: {{< url path="Cortex.Reference.Glossary.F-J.File" >}} +[flows]: {{< url path="Cortex.Reference.Glossary.F-J.Flow" >}} +[flow developers]: {{< url path="Cortex.Reference.Glossary.F-J.FlowDeveloper" >}} +[heterogenous]: {{< url path="Cortex.Reference.Glossary.F-J.Heterogenous" >}} +[homogenous]: {{< url path="Cortex.Reference.Glossary.F-J.Homogenous" >}} +[integer]: {{< url path="Cortex.Reference.Glossary.F-J.Integer" >}} +[item]: {{< url path="Cortex.Reference.Glossary.F-J.Item" >}} +[list]: {{< url path="Cortex.Reference.Glossary.K-O.List" >}} +[platform]: {{< url path="Cortex.Reference.Glossary.P-T.Platform" >}} +[programming language]: {{< url path="Cortex.Reference.Glossary.P-T.ProgrammingLanguage" >}} +[snippets]: {{< url path="Cortex.Reference.Glossary.P-T.Snippets" >}} +[variable]: {{< url path="Cortex.Reference.Glossary.U-Z.Variable" >}} + +[List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} + +[Fundamentals > Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[Text > Format Parameters]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatTemplates" >}} +[Text > Format Specifiers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatSpecifiers" >}} +[Text > Format Templates]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Formatting.FormatTemplates" >}} +[Working With > Invariant Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.InvariantCulture.MainDoc" >}} +[Block Properties > Input Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Block Properties > InputOutput Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[collection]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} +[Collections > Indexes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Indexes.MainDoc" >}} +[CORTEX Studio > Authorisation]: {{< url path="Cortex.Guides.Gateway.Settings.StudioAuthorisation.MainDoc" >}} + +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} + +[Casting and type conversions (C# Programming Guide)]: {{< url path="MSDocs.CSharp.Casting" >}} + +[What is Json (W3)]: {{< url path="W3.WhatIsJson" >}} + +[Information Technology (Wikipedia)]: {{< url path="Wikipedia.InformationTechnology" >}} + +[WHATWG entity list]: {{< url path="WHATWG.EntityList" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/k-o.md b/content/en/docs/2024.9/Reference/Glossary/k-o.md new file mode 100644 index 000000000..e13a3bcc2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/k-o.md @@ -0,0 +1,162 @@ +--- +title: "K-O" +linkTitle: "K-O" +description: "Terms, words and phrases beginning with the letters K through O." +weight: 30 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the letters K through O. + +## K + +## L + +### Linux + +Linux is an open-source Unix-like operating system based on the Linux kernel. + +### List + +A [data type][] that represents a list of items that can iterated or looped over. + +For more detailed information about the List data type, see [Data Types > List<TItem>][]. + +### Literal + +A literal is an explicit value that is not calculated during the execution of the flow. A literal can be any of the following data types: + +- [String][] +- [Char][] +- [Int32][] +- [Int64][] +- [Double][] +- [Single][] +- [Boolean][] +- [Object][] +- [Dictionary][] +- [Structure][] +- [List][] + +### lowercase + +The term lowercase refers to small letters (a,b,c ...) as distinguished from capital letters (A,B,C...). + +### Low-code + +Low-code is an approach to developing [automation][] through a [graphical user interface (GUI)][GUI] that requires little to no coding; where the [developers][] predominantly use [drag-and-drop][] features, rather than writing [code][]. + +## M + +### Method + +In [C#][], a Method is used to execute behaviour of a [data type][] (e.g. the `ToString()` method returns a text representation of the data type). + +See [Method Expressions][] for information on how methods can be used within the [expression editor][]. + +## N + +### Non-Null + +Non-Null indicates that a [data type][] has been [initialised][] and has a value. + +### NServiceBus + +NServiceBus is a messaging framework built on top of Azure Service Bus, it is used to abstract messaging infrastructure within [Service Fabric][]. + +### Nuget Package + +A NuGet package is a ZIP file with the .nupkg extension. It contains compiled code ([DLLs][]), other files related to that code. + +NuGet can be published and shared to a public or private host. + +### Null + +Null indicates that a [data type][] has been [initialised][] with no value. + +## O + +### Object + +A [data type][] that indicates that any data type can be used. + +For more detailed information about the Object data type, see [Data Types > Object][]. + +### Occurrence + +A value can occur in a [collection][] multiple times, these are called Occurrences. + +Occurrences are 1 based (e.g. The first occurrence of an item in a list is at occurrence 1, the second occurrence of an item is at occurrence 2, etc.). + +See [Collections > Occurrences][]. + +### On-premise + +On-premise refers to infrastructure and software that is deployed and running within a physical location of an organisation. + +### Operand + +Describes a [literal][] or [variable][] that has the capability to be operated on. For example, in the [expression][] `1 + 2` the literal values `1` and `2` are operands, whereas `+` is an [operator][]. + +### Operator + +Operators are used to manipulate and check operands values. For example, in the [expression][] `1 + 2` the operator `+` adds the two [operands][operand] `1` and `2`, resulting in the expression evaluating to `3`. + +For more detailed information about operators, see [C# operators and expressions][]. + +### Output + +Output properties are used to save values from a [block][blocks]. These properties will saved to a [variable][] during the block’s execution. + +See [Block Properties > Output Properties][]. + +### Out-of-the-box (OOTB) + +Out-of-the-box functionality of a product that works immediately after any installation without any configuration or modification. + +### Outlook + +Outlook is a free web-based email service provided by Microsoft. + +[List]: {{< ref "#list" >}} +[literal]: {{< ref "#literal" >}} +[operand]: {{< ref "#operand" >}} +[operator]: {{< ref "#operator" >}} +[Object]: {{< ref "#object" >}} + +[expression]: {{< url path="Cortex.Reference.Glossary.A-E.Expression" >}} +[variable]: {{< url path="Cortex.Reference.Glossary.U-Z.Variable" >}} + +[automation]: {{< url path="Cortex.Reference.Glossary.A-E.Automation" >}} +[blocks]: {{< url path="Cortex.Reference.Glossary.A-E.Block" >}} +[Boolean]: {{< url path="Cortex.Reference.Glossary.A-E.Boolean" >}} +[Char]: {{< url path="Cortex.Reference.Glossary.A-E.Char" >}} +[code]: {{< url path="Cortex.Reference.Glossary.A-E.Code" >}} +[C#]: {{< url path="Cortex.Reference.Glossary.A-E.CSharp" >}} +[data type]: {{< url path="Cortex.Reference.Glossary.A-E.DataType" >}} +[developers]: {{< url path="Cortex.Reference.Glossary.A-E.Developer" >}} +[DLLs]: {{< url path="Cortex.Reference.Glossary.A-E.DLL" >}} +[drag-and-drop]: {{< url path="Cortex.Reference.Glossary.A-E.DragAndDrop" >}} +[Dictionary]: {{< url path="Cortex.Reference.Glossary.A-E.Dictionary" >}} +[Double]: {{< url path="Cortex.Reference.Glossary.A-E.Double" >}} +[expression editor]: {{< url path="Cortex.Reference.Glossary.A-E.ExpressionEditor" >}} +[GUI]: {{< url path="Cortex.Reference.Glossary.F-J.GUI" >}} +[initialised]: {{< url path="Cortex.Reference.Glossary.F-J.Initialised" >}} +[Int32]: {{< url path="Cortex.Reference.Glossary.F-J.Int32" >}} +[Int64]: {{< url path="Cortex.Reference.Glossary.F-J.Int32" >}} +[Single]: {{< url path="Cortex.Reference.Glossary.P-T.Single" >}} +[String]: {{< url path="Cortex.Reference.Glossary.P-T.String" >}} +[Service Fabric]: {{< url path="Cortex.Reference.Glossary.P-T.ServiceFabric" >}} +[Structure]: {{< url path="Cortex.Reference.Glossary.P-T.Structure" >}} + +[Method Expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MethodExpressions" >}} +[collection]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} +[Data Types > List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Data Types > Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} + +[Block Properties > Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Collections > Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} + +[C# operators and expressions]: {{< url path="MSDocs.CSharp.OperatorsAndExpressions" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/p-t.md b/content/en/docs/2024.9/Reference/Glossary/p-t.md new file mode 100644 index 000000000..fde521c1e --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/p-t.md @@ -0,0 +1,210 @@ +--- +title: "P-T" +linkTitle: "P-T" +description: "Terms, words and phrases beginning with the letters P through T." +weight: 40 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the letters P through T. + +## P + +### PascalCase + +PascalCase is a typographical convention in which phrases are written without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word also starting with a capitalized letter. E.g. "FirstName" and "LastName". + +PascalCase is often used as a naming convention in programming languages such as [C#][]. + +See also [camelCase][]. + +### Platform + +The environment in which software is executed. This can include the hardware, operating system, web browsers or other programs. + +### Portal + +A portal is a specially designed website that serves as a single point of access for information or functionality. + +### PowerShell + +See [Windows PowerShell][] + +### PowerShell Core + +An open-source version of [PowerShell][Windows PowerShell] that can be run on various platforms, such as: + +- Linux +- macOs +- Windows + +See [What is PowerShell?][] for more information about PowerShell Core and Windows PowerShell. + +### Process + +A process is a collection of related, structured [tasks][] completed by people or equipment in a specific sequence. + +### Programming Language + +A programming language is a notation for writing computer programs, which are specifications of a computation or algorithm. + +### Property + +#### Block (property) + +See [Block Property][]. + +#### C# (property) + +In [C#][], a Property is used to access or update attributes of a [data type][] (e.g. the `Message` property of an [Exception][] returns the reason the exception occurred). + +See [Property Expressions][] for information on how properties can be used within the [expression editor][]. + +### Property Type + +There are three types of [block property][]: + +- [Input Properties][] +- [Output Properties][] +- [InputOutput Properties][] + +See [Block Properties > What is a Block Property][]. + +## Q + +## R + +### Read-only + +Refers to computer files or memory that can be read or used, but not updated or added to in any way. + +### Release + +A Release follows a longer term release cycle, allowing access to the latest stable version of {{% ctx %}} and longer term support. + +### Request + +A method of communication over a network, in which one computer sends a request to another, which can then respond to the request. + +## S + +### SASL + +Simple Authentication and Security Layer (SASL) is a framework for protocols like [SMTP][] and [IMAP][] to add authentication support. + +### SDK + +SDK stands for "Software Development Kit", and is a collection of software development tools. + +An SDK facilitates the creation of applications by having a compiler, debugger and sometimes a software framework. + +### Service Fabric + +Service Fabric is an open source project developed by Microsoft used to deliver highly available and durable services at cloud-scale. + +For more information see [What is Service Fabric?][] + +### Single + +A [data type][] that represents a fractional, or very large or small number from `-3.402823e+38` through `3.402823e+38`. + +For more detailed information about the Single data type, see [Data Types > Single][]. + +### SMTP + +Simple Mail Transfer Protocol (SMTP) is an internet protocol for email transmission. Mail servers typically only use SMTP to send emails. + +### Snippets + +Snippet is a term for a small section of re-usable code. + +Snippets can be accessed from any editor using [Intellisense][]. + +### Software Development + +The process of developing software. + +### SSL + +Secure Sockets Layer (SSL) is the technology that keeps an internet connection secure via the encryption of data in transit. + +### String + +A [data type][] that represents text. + +For more detailed information about the String data type, see [Data Types > String][]. + +### Structure + +A [data type][] that represents a collection of key/item pairs, where each pair consists of a unique [String][Data Types > String] key and its associated item. + +For more detailed information about the Structure data type, see [Data Types > Structure][]. + +### Syntax Highlighting + +Syntax highlighting is a feature of text editors that are used for programming. The feature displays text in different colours and fonts according to a category of terms. + +Syntax Highlighting improves the readability and provides context of text, and can be used to identify errors within a block of [code][]. + +## T + +### Task + +A unit of work to be done or undertaken. + +### Text + +Data which can be interpreted as human-readable text, this is represented by [Strings][Data Types > String] in [C#][]. + +### Title Case + +Title Case is a typographical convention in which the first letter of all words are capitalized and all other letters lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased. + +### TLS + +Transport Layer Security is a more secure, updated version of [SSL][]. Note that TLS is still often referred to as [SSL][]. + +### Trigger + +A mechanism used to initiate an action when a specific event occurs (e.g. When a given date or time is reached). + +### Type + +See [Data Type][data type]. + +### Typeahead + +Typeahead is a language prediction tool that is used to provide suggestions based on what a user has already typed. + +[SMTP]: {{< ref "#smtp" >}} +[SSL]: {{< ref "#ssl" >}} + +[Block Property]: {{< url path="Cortex.Reference.Glossary.A-E.BlockProperty" >}} +[C#]: {{< url path="Cortex.Reference.Glossary.A-E.CSharp" >}} +[camelCase]: {{< url path="Cortex.Reference.Glossary.A-E.CamelCase" >}} +[code]: {{< url path="Cortex.Reference.Glossary.A-E.Code" >}} +[data type]: {{< url path="Cortex.Reference.Glossary.A-E.DataType" >}} +[expression editor]: {{< url path="Cortex.Reference.Glossary.A-E.ExpressionEditor" >}} +[Intellisense]: {{< url path="Cortex.Reference.Glossary.F-J.Intellisense" >}} +[IMAP]: {{< url path="Cortex.Reference.Glossary.F-J.IMAP" >}} +[tasks]: {{< url path="Cortex.Reference.Glossary.P-T.Task" >}} +[Windows PowerShell]: {{< url path="Cortex.Reference.Glossary.U-Z.WindowsPowerShell" >}} + +[Data Types > String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Data Types > Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Data Types > Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} + +[Exception]: {{< url path="Cortex.Reference.Exceptions.MainDoc" >}} + +[Block Properties > What is a Block Property]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.MainDoc" >}} + +[Input Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output Properties]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Property Expressions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.PropertyExpressions" >}} + +[What is PowerShell?]: {{< url path="MSDocs.PowerShell.WhatIsPowerShell" >}} + +[What is Service Fabric?]: {{< url path="MSDocs.ServiceFabric.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/Glossary/u-z.md b/content/en/docs/2024.9/Reference/Glossary/u-z.md new file mode 100644 index 000000000..116339f71 --- /dev/null +++ b/content/en/docs/2024.9/Reference/Glossary/u-z.md @@ -0,0 +1,67 @@ +--- +title: "U-Z" +linkTitle: "U-Z" +description: "Terms, words and phrases beginning with the letters U through Z." +weight: 50 +--- + +# {{% param title %}} + +Terms, words and phrases beginning with the letters U through Z. + +## U + +### Unicode + +Unicode is a standard used to ensure consistent encoding, representation, and handling of text. + +See [What is Unicode?][]. + +### UPPERCASE + +The term uppercase refers to capital letters (A,B,C...) as distinguished from small letters (a,b,c ...). + +## V + +### Variable + +A variable is a named container for storing data that can then be used in [Block Properties][]. + +Data in a variable can be read, updated, or removed by different blocks. + +For more detailed information about variables, see [Fundamentals > Variables][]. + +## W + +### Whitespace + +In programming, whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character does not correspond to a visible character, but typically does occupy an area on a page. + +See [Text > Empty Text and Whitespace][]. + +### Windows PowerShell + +PowerShell is a task automation and configuration management program from Microsoft, consisting of a command-line shell and the associated scripting language. + +See [What is PowerShell?][] for more information about PowerShell Core and Windows PowerShell. + +## X + +## Y + +## Z + +### Zero Based + +Zero Based is a way of numbering in which the initial item of a list is assigned the [index][] `0`. + +[index]: {{< url path="Cortex.Reference.Glossary.F-J.Index" >}} + +[Block Properties]: {{< url path="Cortex.Reference.Glossary.A-E.BlockProperty" >}} +[Fundamentals > Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} + +[Text > Empty Text and Whitespace]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.EmptyTextAndWhitespace.MainDoc" >}} + +[What is Unicode?]: {{< url path="Unicode.WhatIsUnicode" >}} + +[What is PowerShell?]: {{< url path="MSDocs.PowerShell.WhatIsPowerShell" >}} diff --git a/content/en/docs/2024.9/Reference/_index.md b/content/en/docs/2024.9/Reference/_index.md new file mode 100644 index 000000000..403754f09 --- /dev/null +++ b/content/en/docs/2024.9/Reference/_index.md @@ -0,0 +1,6 @@ +--- +title: "Reference" +linkTitle: "Reference" +description: "This section includes all reference documentation for the {{% ctx %}} Innovation platform." +weight: 100 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/_index.md b/content/en/docs/2024.9/Reference/data-types/_index.md new file mode 100644 index 000000000..fc92973ac --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/_index.md @@ -0,0 +1,6 @@ +--- +title: "Data Types" +linkTitle: "Data Types" +description: "This section includes all reference documentation for data types." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/all/_index.md b/content/en/docs/2024.9/Reference/data-types/all/_index.md new file mode 100644 index 000000000..ad74c877d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/all/_index.md @@ -0,0 +1,6 @@ +--- +title: "All" +linkTitle: "All" +description: "Data types used to represent all other data types." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/all/dynamic.md b/content/en/docs/2024.9/Reference/data-types/all/dynamic.md new file mode 100644 index 000000000..a86e1e7a7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/all/dynamic.md @@ -0,0 +1,83 @@ +--- +title: "dynamic" +linkTitle: "dynamic" +description: "Any data type can be used where a `dynamic` data type is required. `dynamic` data type is identical to the `Object` data type, except for one difference; `dynamic` data types do not need to be explicitly cast to other data types to be used, whereas `Object` data types do." +--- + +# {{% param title %}} + +## Summary + +Any data type can be used where a `dynamic` data type is required. + +`dynamic` data type is identical to the [Object][] data type, except for one difference; `dynamic` data types do not need to be explicitly cast to other data types to be used, whereas [Object][] data types do. + +| | | +|-|-| +| **Category:** | All | +| **Name:** | `dynamic` | +| **Full Name:** | N/A | +| **Alias:** | N/A | +| **Description:** | Any data type can be used where a `dynamic` data type is required. `dynamic` data type is identical to the [Object][] data type, except for one difference; `dynamic` data types do not need to be explicitly cast to other data types to be used, whereas [Object][] data types do. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### When is the dynamic Data Type Used? + +The `dynamic` data type is only likely to be encountered in the following circumstances: + +* An [Input][] or [InputOutput][] property of a Block can accept any data type +* An [Output][] property of a Block can return any data type +* A [Collection][] that contains different data types (e.g. `[1, "Text", true]`) is saved to a [Variable][] + +Also note, in these circumstances it is more likely to encounter the `dynamic` data type, rather than [Object][]. See [Object vs dynamic][] for more information. + +### Object vs dynamic + +[Object][] and `dynamic` data types are identical, except for one difference: + +* Once a variable contains an [Object][] data type, if it needs to be used as its original data type it must be cast back to that data type (e.g. `(Int32)($)ObjectVariableContainingAnInteger`); a `dynamic` data type does not. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `dynamic`. +* The Literal Editor is not available for [Input][] properties where the data type is `dynamic`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `dynamic`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Object][] + +### Related Concepts + +None + +### External Documentation + +* [Using dynamic][] + +[Object vs dynamic]: {{< ref "#object-vs-dynamic" >}} + +[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" >}} + +[Collection]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[System.Object]: {{< url path="MSDocs.DotNet.Api.System.Object.MainDoc" >}} +[Using dynamic]: {{< url path="MSDocs.DotNet.Api.System.dynamic.MainDoc" >}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/all/object.md b/content/en/docs/2024.9/Reference/data-types/all/object.md new file mode 100644 index 000000000..e1dc90c7d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/all/object.md @@ -0,0 +1,92 @@ +--- +title: "Object" +linkTitle: "Object" +description: "Any data type can be used where an `Object` data type is required, as all data types derive from `Object`." +--- + +# {{% param title %}} + +

(System.Object)

+ +## Summary + +Any data type can be used where an `Object` data type is required, as all data types derive from `Object`. + +`Object` data type is identical to the [dynamic][] data type, except for one difference; [dynamic][] data types do not need to be explicitly cast to other data types to be used, whereas `Object` data types do. + +| | | +|-|-| +| **Category:** | All | +| **Name:** | `Object` | +| **Full Name:** | `System.Object` | +| **Alias:** | `object` | +| **Description:** | Any data type can be used where an `Object` data type is required, as all data types derive from `Object`. `Object` data type is identical to the [dynamic][] data type, except for one difference; [dynamic][] data types do not need to be explicitly cast to other data types to be used, whereas `Object` data types do. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### When is the Object Data Type Used? + +The `Object` data type is only likely to be encountered in the following circumstances: + +* An [Input][] or [InputOutput][] property of a Block can accept any data type +* An [Output][] property of a Block can return any data type +* A [Collection][] that contains different data types (e.g. `[1, "Text", true]`) is saved to a [Variable][] + +Also note, in these circumstances it is more likely to encounter the [dynamic][] data type, rather than `Object`. See [Object vs dynamic][] for more information. + +It is also highly unlikely that you will need to create an `Object`; typically you will create and work with other data types such as [String][] or [Int32][] that derive from `Object`. However, if ever required you can create a new object using the following expression: + +```csharp +new Object() +``` + +### Object vs dynamic + +`Object` and [dynamic][] data types are identical, except for one difference: + +* Once a variable contains an `Object` data type, if it needs to be used as its original data type it must be cast back to that data type (e.g. `(Int32)($)ObjectVariableContainingAnInteger`); a [dynamic][] data type does not. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Object`. +* The Literal Editor is not available for [Input][] properties where the data type is `Object`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Object`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [dynamic][] + +### Related Concepts + +None + +### External Documentation + +* [System.Object][] +* [Using dynamic][] + +[Object vs dynamic]: {{< ref "#object-vs-dynamic" >}} + +[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" >}} + +[Collection]: {{< url path="Cortex.Reference.DataTypes.Collections.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.MainDoc" >}} + +[System.Object]: {{< url path="MSDocs.DotNet.Api.System.Object.MainDoc" >}} +[Using dynamic]: {{< url path="MSDocs.DotNet.Api.System.dynamic.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/_index.md b/content/en/docs/2024.9/Reference/data-types/collections/_index.md new file mode 100644 index 000000000..63ba83fc5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/_index.md @@ -0,0 +1,6 @@ +--- +title: "Collections" +linkTitle: "Collections" +description: "Data types used for working with collections such as Lists, Dictionaries and Structures." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/collections/array.md b/content/en/docs/2024.9/Reference/data-types/collections/array.md new file mode 100644 index 000000000..c4b7db754 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/array.md @@ -0,0 +1,114 @@ +--- +title: "Array" +linkTitle: "Array" +description: "Any data type representing an array of items. The type of items that can be contained in the array depend upon the type of the array. Common examples include arrays of strings and integers (i.e. `String[]` and `Int32[]`)." +--- + +# {{% param title %}} + +

(System.Array)

+ +## Summary + +Any data type representing an array of items. + +The type of items that can be contained in the array depend upon the type of the array. + +Common examples include arrays of strings and integers (i.e. `String[]` and `Int32[]`); for more see [Most Common Array Data Types][]. + +Arrays are very similar to Lists, but have some key differences, such as they are a fixed size and cannot be added to, or deleted from. For more information about the differences between Arrays and Lists, and when to use each of them see [Arrays vs Lists][]. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `Array` | +| **Full Name:** | `System.Array` | +| **Alias:** | N/A | +| **Description:** | Any data type representing an array of items. The type of items that can be contained in the array depend upon the type of the array. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IEnumerable`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common Array Data Types + +Any of the following data types can be used where an `Array` is required: + +* `Object[]` - an array containing [Object][] items +* `String[]` - an array containing [String][] items +* `Boolean[]` - an array containing [Boolean][] items +* `Int16[]` - an array containing [Int16][] items +* `Int32[]` - an array containing [Int32][] items +* `Int64[]` - an array containing [Int64][] items +* `Single[]` - an array containing [Single][] items +* `Double[]` - an array containing [Double][] items + +### Create an Array + +The following table shows some of the ways that an `Array` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an explicit `Array` expression | `new Object[] {}` | `[]` | Expression | `Object[]` containing zero items | +| | `new String[] { "Some Text" }` | `["Some Text"]` | Expression | `String[]` containing one String item | +| | `new Boolean[] { true, false }` | `[true, false]` | Expression | `Boolean[]` containing two Boolean items | +| | `new Int32[] { 1, 2, 3 }` | `[1, 2, 3]` | Expression | `Int32[]` containing three Int32 items | +| | `new Object[] { "Some Text", true, 1 }`| `["Some Text", true, 1]` | Expression | `Object[]` containing a String item, a Boolean item and an Int32 item | +| Use an implicit `Array` expression | `new [] { "Some Text" }` | `["Some Text"]` | Expression | `String[]` containing one String item. Implicit arrays must only contain a single data type | +| | `new [] { true, false }` | `[true, false]` | Expression | `Boolean[]` containing two Boolean items | +| | `new [] { 1, 2, 3 }` | `[1, 2, 3]` | Expression | `Int32[]` containing three Int32 items | + +### Convert Array to Text + +The following table shows some of the ways that an `Array` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has an `Object[]` value of `["Some Text", true, 1]` | `"[\r\n \"Some Text\",\r\n true,\r\n 1\r\n]"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +Currently no [Input][], [InputOutput][] or [Output][] properties require the `Array` data type. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Array][] + +[Most Common Array Data Types]: {{< ref "#most-common-array-data-types" >}} + +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[System.Array]: {{< url path="MSDocs.DotNet.Api.System.Array" >}} + +[Object]: {{< url path="Cortex.Reference.DataTypes.All.Object.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} +[Arrays vs Lists]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.WhatIsACollection.ArraysVersusLists" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/dictionary-2.md b/content/en/docs/2024.9/Reference/data-types/collections/dictionary-2.md new file mode 100644 index 000000000..ff599e65c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/dictionary-2.md @@ -0,0 +1,96 @@ +--- +title: "Dictionary" +linkTitle: "Dictionary" +description: "Used to represent a collection of key/item pairs. `TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key." +--- + +# {{% param title %}} + +

(System.Collections.Generic.Dictionary<TKey, TItem>)

+ +## Summary + +The `Dictionary` data type is used to represent a collection of key/item pairs. + +`TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `Dictionary` | +| **Full Name:** | `System.Collections.Generic.Dictionary` | +| **Alias:** | N/A | +| **Description:** | A collection of key/item pairs. `TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IDictionary`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable>` (e.g. where `Dictionary` is `Dictionary` and `IEnumerable>` is `IEnumerable>`) | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a Dictionary<TKey, TItem> + +The following table shows some of the ways that a `Dictionary` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Dictionary` expression | `new Dictionary()` | `{}` | Expression | `Dictionary` containing zero items | +| | `new Dictionary() { { "StringKey1", "StringValue" } }` | `{ "StringKey1": "StringValue" }` | Expression | `Dictionary` containing one String item with a String key | +| | `new Dictionary() { { "StringKey1", true }, { "StringKey2", false } }` | `{ "StringKey1": true, "StringKey2": false }` | Expression | `Dictionary` containing two Boolean items with String keys | +| | `new Dictionary() { { "StringKey1", 1 }, { "StringKey2", 2 }, { "StringKey3", 3 } }`| `{ "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 }` | Expression | `Dictionary` containing three Int32 item with String keys| +| | `new Dictionary() { { "StringKey1", "StringValue" }, { "StringKey2", true }, { "StringKey3", 1 } }`| `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }` | Expression | `Dictionary` containing a String item, a Boolean item and an Int32 item with String keys | + +### Convert Dictionary<TKey, TItem> to Text + +The following table shows some of the ways that a `Dictionary` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a `Dictionary` value of `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }` | `"{\r\n \"StringKey1\": \"StringValue\",\r\n \"StringKey2\": true,\r\n \"StringKey3\": 1\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Dictionary`. +* The Literal Editor is not available for [Input][] properties where the data type is `Dictionary`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Dictionary`. + +### Known Limitations + +* Currently, only certain data types can be used for `TKey`. These include, but not limited to: + * `String` + * `Int32` + * `Double` + * `Boolean` + * `DateTimeOffset` +* If the data type of `TKey` is anything other than a `String`, when viewing the `Dictionary` in Gateway the key value will be displayed as its `ToString()` representation (e.g. an `Int32` key value of `1` will be displayed as `"1"` instead of `1`). + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [IDictionary<TKey, TItem>][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.Dictionary<TKey, TItem>][] + +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[System.Collections.Generic.Dictionary<TKey, TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.Dictionary" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IDictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/icomparer-1.md b/content/en/docs/2024.9/Reference/data-types/collections/icomparer-1.md new file mode 100644 index 000000000..03b5bbe64 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/icomparer-1.md @@ -0,0 +1,87 @@ +--- +title: "IComparer" +linkTitle: "IComparer" +description: "Any data type representing a comparer that can be used to order two values of `TPriority`." +--- + +# {{% param title %}} + +

(System.Collections.Generic.IComparer<TPriority>)

+ +## Summary + +Any data type representing a comparer that can be used to order two values of [TPriority][]. + +`TPriority` indicates the data type of the priorities that are being compared. + +`StringComparer` is the most common example. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IComparer` | +| **Full Name:** | `System.Collections.Generic.IComparer` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a comparer that can be used to order two values of [TPriority][]. | +| **Default Value:** | `null` | +| **Can be used as:** | `IComparer`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IComparer<TPriority> Data Types + +Any of the following data types can be used where an `IComparer` is required: + +* [StringComparer][] + +### Create an IComparer<TPriority> + +For some of the ways that an `IComparer` can be created, please see each of the `IComparer` data types: + +* [StringComparer][StringComparerCreateNew] + +### Convert IComparer<TPriority> to Text + +For some of the ways that an `IComparer` can be converted to text, please see each of the `IComparer` data types: + +* [StringComparer][StringComparerConvertToText] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IComparer`. +* The Literal Editor is not available for [Input][] properties where the data type is `IComparer`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IComparer`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [StringComparer][] +* [QueueWithPriority][] + +### Related Concepts + +None + +### External Documentation + +* [System.Collections.Generic.IComparer<TItem>][IComparer] + +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[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" >}} + +[IComparer]: {{< url path="MSDocs.DotNet.Api.System.IComparer.MainDoc" >}} + +[QueueWithPriority]: {{< url path="Cortex.Reference.DataTypes.Collections.QueueWithPriority.MainDoc" >}} + +[StringComparer]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparer.MainDoc">}} +[StringComparerConvertToText]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparer.ConvertToText">}} +[StringComparerCreateNew]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparer.CreateNew">}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/idictionary-2.md b/content/en/docs/2024.9/Reference/data-types/collections/idictionary-2.md new file mode 100644 index 000000000..3a48bb474 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/idictionary-2.md @@ -0,0 +1,103 @@ +--- +title: "IDictionary" +linkTitle: "IDictionary" +description: "Any data type representing a collection of key/item pairs. `TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key. `Dictionary` is the most common example." +--- + +# {{% param title %}} + +

(System.Collections.Generic.IDictionary<TKey, TItem>)

+ +## Summary + +Any data type representing a collection of key/item pairs. + +`TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key. + +`Dictionary` is the most common example. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IDictionary` | +| **Full Name:** | `System.Collections.Generic.IDictionary` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a collection of key/item pairs. `TKey` indicates the data type of the keys used to access the items contained in the collection. `TItem` indicates the data type of the items contained in the collection. Each `TItem` can be individually accessed by a key. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable>` (e.g. where `IDictionary` is `IDictionary` and `IEnumerable>` is `IEnumerable>`) | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IDictionary<TKey, TItem> Data Types + +Any of the following data types can be used where an `IDictionary` is required: + +* [Dictionary<TKey, TItem>][] +* [Structure][] + +### Create an IDictionary<TKey, TItem> + +For some of the ways that an `IDictionary` can be created, please see each of the `IDictionary` data types: + +* [Dictionary<TKey, TItem>][DictionaryCreateNew] +* [Structure][StructureCreateNew] + +### Convert IDictionary<TKey, TItem> to Text + +For some of the ways that an `IDictionary` can be converted to text, please see each of the `IDictionary` data types: + +* [Dictionary<TKey, TItem>][DictionaryConvertToText] +* [Structure][StructureConvertToText] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IDictionary`. +* The Literal Editor is not available for [Input][] properties where the data type is `IDictionary`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IDictionary`. + +### Known Limitations + +* Currently, only certain data types can be used for `TKey`. These include, but not limited to: + * `String` + * `Int32` + * `Double` + * `Boolean` + * `DateTimeOffset` +* If the data type of `TKey` is anything other than a `String`, when viewing the `IDictionary` in Gateway the key value will be displayed as its `ToString()` representation (e.g. an `Int32` key value of `1` will be displayed as `"1"` instead of `1`). + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [Dictionary<TKey, TItem>][] +* [Structure][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.IDictionary<TKey, TItem>][] + +[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" >}} + +[System.Collections.Generic.IDictionary<TKey, TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IDictionary" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[DictionaryCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[DictionaryConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.ConvertToText" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[StructureCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} +[StructureConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.ConvertToText" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/ienumerable-1.md b/content/en/docs/2024.9/Reference/data-types/collections/ienumerable-1.md new file mode 100644 index 000000000..6ccb3223f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/ienumerable-1.md @@ -0,0 +1,115 @@ +--- +title: "IEnumerable" +linkTitle: "IEnumerable" +description: "Any data type representing a collection of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the collection. `List` is the most common example." +--- + +# {{% param title %}} + +

(System.Collections.Generic.IEnumerable<TItem>)

+ +## Summary + +Any data type representing a collection of items that can iterated or looped over. + +`TItem` indicates the data type of the items contained in the collection. + +`List` is the most common example; for more see [Most Common IEnumerable<TItem> Data Types][]. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IEnumerable` | +| **Full Name:** | `System.Collections.Generic.IEnumerable` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a collection of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the collection. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable` (e.g. where `IEnumerable` is `IEnumerable` and `IEnumerable` is `IEnumerable` as `Object` is a base type of `Int32`; this is called covariance) | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IEnumerable<TItem> Data Types + +Any of the following data types can be used where an `IEnumerable` is required: + +* [IList<TItem>][] +* [List<TItem>][] +* [IDictionary<TKey, TItem>][] +* [Dictionary<TKey, TItem>][] +* [Structure][] +* [String][] + +### Create an IEnumerable<TItem> + +For some of the ways that an `IEnumerable` can be created, please see each of the `IEnumerable` data types: + +* [List<TItem>][ListCreateNew] +* [Dictionary<TKey, TItem>][DictionaryCreateNew] +* [Structure][StructureCreateNew] +* [String][StringCreateNew] + +### Convert IEnumerable<TItem> to Text + +For some of the ways that an `IEnumerable` can be converted to text, please see each of the `IEnumerable` data types: + +* [List<TItem>][ListConvertToText] +* [Dictionary<TKey, TItem>][DictionaryConvertToText] +* [Structure][StructureConvertToText] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IEnumerable`. +* The Literal Editor is not available for [Input][] properties where the data type is `IEnumerable`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IEnumerable`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IList<TItem>][] +* [List<TItem>][] +* [IDictionary<TKey, TItem>][] +* [Dictionary<TKey, TItem>][] +* [Structure][] +* [String][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.IEnumerable<TItem>][] + +[Most Common IEnumerable<TItem> Data Types]: {{< ref "#most-common-ienumerablelttitemgt-data-types" >}} + +[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" >}} + +[System.Collections.Generic.IEnumerable<TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IEnumerable_TItem" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IList<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[ListCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[ListConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.List.ConvertToText" >}} +[IDictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[DictionaryCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[DictionaryConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.ConvertToText" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[StructureCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} +[StructureConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.ConvertToText" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringCreateNew]: {{< url path="Cortex.Reference.DataTypes.Text.String.CreateNew" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/ienumerable.md b/content/en/docs/2024.9/Reference/data-types/collections/ienumerable.md new file mode 100644 index 000000000..bb8682d4c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/ienumerable.md @@ -0,0 +1,114 @@ +--- +title: "IEnumerable" +linkTitle: "IEnumerable" +description: "Any data type representing a collection of items that can iterated or looped over. The items contained in the collection can be any data type. `List` is the most common example." +--- + +# {{% param title %}} + +

(System.Collections.IEnumerable)

+ +## Summary + +Any data type representing a collection of items that can iterated or looped over. + +The items contained in the collection can be any data type. + +`List` is the most common example; for more see [Most Common IEnumerable Data Types][]. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IEnumerable` | +| **Full Name:** | `System.Collections.IEnumerable` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a collection of items that can iterated or looped over. The items contained in the collection can be any data type. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IEnumerable Data Types + +Any of the following data types can be used where an `IEnumerable` is required: + +* [IList<TItem>][] +* [List<TItem>][] +* [IDictionary<TKey, TItem>][] +* [Dictionary<TKey, TItem>][] +* [Structure][] +* [String][] + +### Create an IEnumerable + +For some of the ways that an `IEnumerable` can be created, please see each of the `IEnumerable` data types: + +* [List<TItem>][ListCreateNew] +* [Dictionary<TKey, TItem>][DictionaryCreateNew] +* [Structure][StructureCreateNew] +* [String][StringCreateNew] + +### Convert IEnumerable to Text + +For some of the ways that an `IEnumerable` can be converted to text, please see each of the `IEnumerable` data types: + +* [List<TItem>][ListConvertToText] +* [Dictionary<TKey, TItem>][DictionaryConvertToText] +* [Structure][StructureConvertToText] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IEnumerable`. +* The Literal Editor is not available for [Input][] properties where the data type is `IEnumerable`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IEnumerable`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable<TItem>][] +* [IList<TItem>][] +* [List<TItem>][] +* [IDictionary<TKey, TItem>][] +* [Dictionary<TKey, TItem>][] +* [Structure][] +* [String][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.IEnumerable][] + +[Most Common IEnumerable Data Types]: {{< ref "#most-common-ienumerable-data-types" >}} + +[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" >}} + +[System.Collections.IEnumerable]: {{< url path="MSDocs.DotNet.Api.System.Collections.IEnumerable" >}} + +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IList<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[ListCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[ListConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.List.ConvertToText" >}} +[IDictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Dictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[DictionaryCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.CreateNew" >}} +[DictionaryConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.ConvertToText" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[StructureCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} +[StructureConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.ConvertToText" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringCreateNew]: {{< url path="Cortex.Reference.DataTypes.Text.String.CreateNew" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/ilist-1.md b/content/en/docs/2024.9/Reference/data-types/collections/ilist-1.md new file mode 100644 index 000000000..b737e901a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/ilist-1.md @@ -0,0 +1,90 @@ +--- +title: "IList" +linkTitle: "IList" +description: "Any data type representing a list of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. `List` is the most common example." +--- + +# {{% param title %}} + +

(System.Collections.Generic.IList<TItem>)

+ +## Summary + +Any data type representing a list of items that can iterated or looped over. + +`TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. + +`List` is the most common example. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IList` | +| **Full Name:** | `System.Collections.Generic.IList` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a list of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IEnumerable`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable` (e.g. where `IList` is `IList` and `IEnumerable` is `IEnumerable` as `Object` is a base type of `Int32`; this is called covariance) | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IList<TItem> Data Types + +Any of the following data types can be used where an `IList` is required: + +* [List<TItem>][] + +### Create an IList<TItem> + +For some of the ways that an `IList` can be created, please see each of the `IList` data types: + +* [List<TItem>][ListCreateNew] + +### Convert IList<TItem> to Text + +For some of the ways that an `IList` can be converted to text, please see each of the `IList` data types: + +* [List<TItem>][ListConvertToText] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IList`. +* The Literal Editor is not available for [Input][] properties where the data type is `IList`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IList`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [List<TItem>][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.IList<TItem>][] + +[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" >}} + +[System.Collections.Generic.IList<TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IList" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[ListCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.List.CreateNew" >}} +[ListConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.List.ConvertToText" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/ireadonlylist-1.md b/content/en/docs/2024.9/Reference/data-types/collections/ireadonlylist-1.md new file mode 100644 index 000000000..bab3b34f0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/ireadonlylist-1.md @@ -0,0 +1,66 @@ +--- +title: "IReadOnlyList" +linkTitle: "IReadOnlyList" +description: "Any data type representing a list of items that can iterated or looped over, where the number and order of items is read-only. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index." +--- +# {{% param title %}} + +

(System.Collections.Generic.IReadOnlyList<TItem>)

+ +## Summary + +Any data type representing a list of items that can iterated or looped over, where the number and order of items is read-only. + +`TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `IReadOnlyList` | +| **Full Name:** | `System.Collections.Generic.IReadOnlyList` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a list of items that can iterated or looped over, where the number and order of items is read-only. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. | +| **Default Value:** | `null` | +| **Can be used as:** | `IReadOnlyList`, `IReadOnlyCollection`, `IEnumerable`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable` (e.g. where `IReadOnlyList` is `IReadOnlyList` and `IEnumerable` is `IEnumerable` as `Object` is a base type of `Int32`; this is called covariance) | +| **Can be cast to:** | N/A | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IReadOnlyList`. +* The Literal Editor is not available for [Input][] properties where the data type is `IReadOnlyList`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `IReadOnlyList`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [List<TItem>][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.IReadOnlyList<TItem>][] +* [System.Collections.Generic.IReadOnlyCollection<TItem>][] + +[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" >}} + +[System.Collections.Generic.IReadOnlyList<TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IReadOnlyList" >}} +[System.Collections.Generic.IReadOnlyCollection<TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.IReadOnlyCollection" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[List<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/list-1.md b/content/en/docs/2024.9/Reference/data-types/collections/list-1.md new file mode 100644 index 000000000..4ddf27ab2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/list-1.md @@ -0,0 +1,95 @@ +--- +title: "List" +linkTitle: "List" +description: "Used to represent a list of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index." +--- + +# {{% param title %}} + +

(System.Collections.Generic.List<TItem>)

+ +## Summary + +The `List` data type is used to represent a list of items that can iterated or looped over. + +`TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `List` | +| **Full Name:** | `System.Collections.Generic.List` | +| **Alias:** | N/A | +| **Description:** | A list of items that can iterated or looped over. `TItem` indicates the data type of the items contained in the list. Each `TItem` can be individually accessed by an index. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IList`, `IEnumerable`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable` (e.g. where `List` is `List` and `IEnumerable` is `IEnumerable` as `Object` is a base type of `Int32`; this is called covariance) | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a List<TItem> + +The following table shows some of the ways that a `List` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `List` literal | `[]` | `[]` | Expression | `List` containing zero items | +| | `["Some Text"]` | `["Some Text"]` | Expression | `List` containing one String item | +| | `[true, false]` | `[true, false]` | Expression | `List` containing two Boolean items | +| | `[1, 2, 3]` | `[1, 2, 3]` | Expression | `List` containing three Int32 items | +| | `["Some Text", true, 1]` | `["Some Text", true, 1]` | Expression | `List` containing a String item, a Boolean item and an Int32 item | +| Use a `List` expression | `new List()` | `[]` | Expression | `List` containing zero items | +| | `new List() { "Some Text" }` | `["Some Text"]` | Expression | `List` containing one String item | +| | `new List() { true, false }` | `[true, false]` | Expression | `List` containing two Boolean items | +| | `new List() { 1, 2, 3 }` | `[1, 2, 3]` | Expression | `List` containing three Int32 items | +| | `new List() { "Some Text", true, 1 }`| `["Some Text", true, 1]` | Expression | `List` containing a String item, a Boolean item and an Int32 item | + +### Convert List<TItem> to Text + +The following table shows some of the ways that a `List` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a `List` value of `["Some Text", true, 1]` | `"[\r\n \"Some Text\",\r\n true,\r\n 1\r\n]"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `List`. +* The Literal Editor is not available for [Input][] properties where the data type is `List`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `List`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [IList<TItem>][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +* [System.Collections.Generic.List<TItem>][] + +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[System.Collections.Generic.List<TItem>]: {{< url path="MSDocs.DotNet.Api.System.Collections.Generic.List" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IList<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/queuewithpriority-2.md b/content/en/docs/2024.9/Reference/data-types/collections/queuewithpriority-2.md new file mode 100644 index 000000000..5c969e384 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/queuewithpriority-2.md @@ -0,0 +1,110 @@ +--- +title: "QueueWithPriority" +linkTitle: "QueueWithPriority" +description: "Used to represent a queue which orders items by priority and preserves first-in-first-out behaviour for items with the same priority." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Queues.QueueWithPriority<TItem, TPriority>)

+ +## Summary + +The `QueueWithPriority` data type is used to represent a queue which orders items by priority (like a [PriorityQueue][]), but preserves first-in-first-out behaviour for items with the same priority. + +When enqueuing items into the `QueueWithPriority`, [TPriority][] is used to order items within the queue. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `QueueWithPriority` | +| **Full Name:** | `Cortex.DataTypes.Queues.QueueWithPriority` | +| **Alias:** | N/A | +| **Description:** | A queue which orders items by priority (like a [PriorityQueue][]), but preserves first-in-first-out behaviour for items with the same priority. When enqueuing items into the `QueueWithPriority`, [TPriority][] is used to order items within the queue.| +| **Default Value:** | `null` | +| **Can be used as:** | `QueueWithPriority`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### PriorityComparer + +The [IComparer][]<[TPriority][]> used to compare [TPriority][] values. + +| | | +|--------------------|---------------------------| +| Data Type | [IComparer][]<[TPriority][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)PriorityComparer` with no value. | + +## Exceptions + +The exceptions thrown by the data type can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [TPriority][] does not implement [IComparer][]<[TPriority][]>. | +| [ArgumentNullException][] | Thrown when [PriorityComparer][PriorityComparer Property] is `null`. | + +## Remarks + +### Create a QueueWithPriority<TItem, TPriority> + +The following table shows some of the ways that a `QueueWithPriority` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `QueueWithPriority` constructor | `new QueueWithPriority()` | `{"Items": [], "PriorityComparer": {}}` | Expression | This constructor will try and use the default comparer defined for [TPriority][]; only data types that implement [IComparer][]<[TPriority][]> have a default comparer.

 If [TPriority][] does not implement [IComparer][]<[TPriority][]> it will not have a default comparer and throw an [ArgumentException][], in this case you must use the constructor in the example below to provide a valid comparer. | +| | `new QueueWithPriority(System.StringComparer.Ordinal)` | `{"Items": [], "PriorityComparer": {"_ignoreCase": false}}` | Expression | This constructor will use the specified [IComparer][]<[TPriority][]> to order the items in the queue by priority. | + +### Convert QueueWithPriority<TItem, TPriority> to Text + +The following table shows some of the ways that a `QueueWithPriority` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a `QueueWithPriority` value of `{"Items": [{"Item": "Something","Priority": 1}],"PriorityComparer": {}}` | `"{\r\n  \"Items\": [\r\n    {\r\n      \"Item\": \"Something\",\r\n      \"Priority\": 1\r\n    }\r\n  ],\r\n  \"PriorityComparer\": {}\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `QueueWithPriority`. +* The Literal Editor is not available for [Input][] properties where the data type is `QueueWithPriority`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `QueueWithPriority`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IComparer<TPriority>][IComparer] + +### Related Concepts + +None + +### External Documentation + +* [System.Collections.Generic.PriorityQueue<TElement,TPriority>][PriorityQueue] + +[PriorityComparer Property]: {{< ref "#prioritycomparer" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[ArgumentNullException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentNullException" >}} + +[PriorityQueue]: {{< url path="MSDocs.DotNet.Api.System.PriorityQueue.MainDoc" >}} +[IComparer]: {{< url path="Cortex.Reference.DataTypes.Collections.IComparer.MainDoc" >}} + +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[TPriority]: {{< url path="Cortex.Reference.Concepts.Fundamentals.DataTypes.Generics.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/collections/structure.md b/content/en/docs/2024.9/Reference/data-types/collections/structure.md new file mode 100644 index 000000000..6a82bbaa4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/collections/structure.md @@ -0,0 +1,93 @@ +--- +title: "Structure" +linkTitle: "Structure" +description: "Used to represent a collection of key/item pairs, where the data type of the keys used to access the items contained in the collection is `String` and the items contained in the collection can be any data type. Each item can be individually accessed by its `String` key." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Dictionaries.Structure)

+ +## Summary + +The `Structure` data type is used to represent a collection of key/item pairs. + +The data type of the keys used to access the items contained in the collection is `String` and the items contained in the collection can be any data type. Each item can be individually accessed by its `String` key. + +| | | +|-|-| +| **Category:** | Collections | +| **Name:** | `Structure` | +| **Full Name:** | `Cortex.DataTypes.Dictionaries.Structure` | +| **Alias:** | N/A | +| **Description:** | Used to represent a collection of key/item pairs, where the data type of the keys used to access the items contained in the collection is `String` and the items contained in the collection can be any data type. Each item can be individually accessed by its `String` key. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `IDictionary`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable>` (e.g. where `Structure` is `IDictionary` and `IEnumerable>` is `IEnumerable>`) | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a Structure + +The following table shows some of the ways that a `Structure` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `Structure` literal | `{}` | `{}` | Expression | `Structure` containing zero items | +| | `{ "StringKey1": "StringValue" }` | `{ "StringKey1": "StringValue" }` | Expression | `Structure` containing one String item with a String key | +| | `{ "StringKey1": true, "StringKey2": false }` | `{ "StringKey1": true, "StringKey2": false }` | Expression | `Structure` containing two Boolean items with String keys | +| | `{ "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 }`| `{ "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 }` | Expression | `Structure` containing three Int32 item with String keys| +| | `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }`| `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }` | Expression | `Structure` containing a String item, a Boolean item and an Int32 item with String keys | +| Use a `Structure` expression | `new Structure()` | `{}` | Expression | `Structure` containing zero items | +| | `new Structure() { { "StringKey1", "StringValue" } }` | `{ "StringKey1": "StringValue" }` | Expression | `Structure` containing one String item with a String key | +| | `new Structure() { { "StringKey1", true }, { "StringKey2", false } }` | `{ "StringKey1": true, "StringKey2": false }` | Expression | `Structure` containing two Boolean items with String keys | +| | `new Structure() { { "StringKey1", 1 }, { "StringKey2", 2 }, { "StringKey3", 3 } }`| `{ "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 }` | Expression | `Structure` containing three Int32 item with String keys| +| | `new Structure() { { "StringKey1", "StringValue" }, { "StringKey2", true }, { "StringKey3", 1 } }`| `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }` | Expression | `Structure` containing a String item, a Boolean item and an Int32 item with String keys | + +### Convert Structure to Text + +The following table shows some of the ways that a `Structure` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a `Structure` value of `{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 }` | `"{\r\n \"StringKey1\": \"StringValue\",\r\n \"StringKey2\": true,\r\n \"StringKey3\": 1\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Structure`. +* The Literal Editor is not available for [Input][] properties where the data type is `Structure`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Structure`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [IEnumerable][] +* [IEnumerable<TItem>][] +* [IDictionary<TKey, TItem>][] + +### Related Concepts + +* [Working with Collections][] + +### External Documentation + +N/A + +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IDictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} + +[Working with Collections]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/concurrency/_index.md b/content/en/docs/2024.9/Reference/data-types/concurrency/_index.md new file mode 100644 index 000000000..692e3bee3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/concurrency/_index.md @@ -0,0 +1,6 @@ +--- +title: "Concurrency" +linkTitle: "Concurrency" +description: "Data types used for working with concurrency." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/_index.md b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/_index.md new file mode 100644 index 000000000..ab0a40442 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/_index.md @@ -0,0 +1,6 @@ +--- +title: "Semaphores" +linkTitle: "Semaphores" +description: "Data types used for working with Semaphores." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/queue-settings.md b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/queue-settings.md new file mode 100644 index 000000000..ef72e1363 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/queue-settings.md @@ -0,0 +1,120 @@ +--- +title: "QueueSettings" +linkTitle: "QueueSettings" +description: "Used to represent the configuration settings of a semaphore's queue." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Concurrency.Semaphores.QueueSettings)

+ +## Summary + +The `QueueSettings` data type represents the settings used to configure a [Semaphore's][Semaphore] queue. + +| | | +|---------------------|--------------------------------------------------------------------------------| +| **Category:** | Concurrency | +| **Name:** | `QueueSettings` | +| **Full Name:** | `Cortex.DataTypes.Concurrency.Semaphores.QueueSettings` | +| **Alias:** | N/A | +| **Description:** | Represents the settings used for configuring a [Semaphore's][Semaphore] queue. | +| **Default Value:** | `null` | +| **Can be used as:** | `QueueSettings`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Priority + +The [Priority][Priority Property] of the executions joining the queue. +The queue is ordered by minimal value, so the item with the lowest [Priority][Priority Property] will be dequeued first. + +| | | +|-----------------|-------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### QueueTimeout + +The [QueueTimeout][QueueTimeout Property] is used to set a duration for the maximum amount of time an execution can spend in the queue. +A value of `null` will allow an execution to queue indefinitely. + +| | | +|-----------------|----------------| +| Data Type | [TimePeriod][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `null` | + +## Remarks + +### Create a QueueSettings + +The following table shows some of the ways that `QueueSettings` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-----------------------------------|------------------------------|-------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------| +| Use a `QueueSettings` constructor | `new QueueSettings(0, null)` | `{ "Priority": 0, "QueueTimeout": null }` | Expression | Creates a new [QueueSettings][] that can be used to configure the functions of a [Semaphore's][Semaphore] queue. | + +A [QueueSettings][] can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|----------------|--------------|---------|---------------------------------------------------------------------------------------------------------------| +| `Priority` | `Int32` | `0` | [Priority][Priority Property] defines the priority that executions will enter the queue with. | +| `QueueTimeout` | `TimePeriod` | `null` | [QueueTimeout][QueueTimeout Property] defines the maximum amount of time an execution can spend in the queue. | + +### Convert QueueSettings to Text + +The following table shows some of the ways that a `QueueSettings` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|------------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------------------|---------------------|--------------------------------| +| Use `Convert Object To Json` block | where `Object` property has a value of `{ "Priority": 0, "QueueTimeout": null }` | `"{\r\n \"Priority\": 0,\r\n \"QueueTimeout\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `QueueSettings`. +- The Literal Editor is available for [Input][] properties where the data type is `QueueSettings`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `QueueSettings`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [SemaphoreSettings][] +- [TimePeriod][] + +### Related Concepts + +- [What is a Semaphore?][Semaphore] + +### External Documentation + +None + +[Priority Property]: {{< ref "#priority" >}} +[QueueTimeout Property]: {{< ref "#queuetimeout" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Semaphore]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MainDoc" >}} +[SemaphoreSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.MainDoc" >}} +[QueueSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/semaphore-settings.md b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/semaphore-settings.md new file mode 100644 index 000000000..66e8a16a7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/concurrency/semaphores/semaphore-settings.md @@ -0,0 +1,164 @@ +--- +title: "SemaphoreSettings" +linkTitle: "SemaphoreSettings" +description: "Used to represent the configuration settings of a semaphore." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Concurrency.Semaphores.SemaphoreSettings)

+ +## Summary + +The `SemaphoreSettings` data type represents the settings used to configure a [Semaphore][]. + +| | | +|---------------------|-------------------------------------------------------------| +| **Category:** | Concurrency | +| **Name:** | `SemaphoreSettings` | +| **Full Name:** | `Cortex.DataTypes.Concurrency.Semaphores.SemaphoreSettings` | +| **Alias:** | N/A | +| **Description:** | Represents the settings used for configuring a [Semaphore][]. | +| **Default Value:** | `null` | +| **Can be used as:** | `SemaphoreSettings`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Scope + +The [Scope][Scope Property] is used to define the area in which the [Semaphore][] will operate. + +| | | +|-----------------|--------------------------------| +| Data Type | [ScopeDefinition][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [ScopeDefinition][] with value shown below | + +```json +{ + "Tenant": "ScopeOption.Current", + "System": "ScopeOption.Current", + "Package": "ScopeOption.Current", + "Flow": "ScopeOption.All" +} +``` + +### Name + +The [Name][Name Property] is used to identify the [Semaphore][]. + +| | | +|-----------------|----------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### ConcurrencyLimit + +The [ConcurrencyLimit][ConcurrencyLimit Property] is used to define the maximum number of executions that can be in the [Semaphore][]. + +The specified value for the [ConcurrencyLimit][ConcurrencyLimit Property] may not be used if a [Semaphore][] with the same [Scope][Scope Property] and [Name][Name Property] already exists, see [Multiple Concurrency Limits][MultipleConcurrencyLimits] for more information. + +| | | +|-----------------|-------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `0` | + +### Queue + +The [Queue][Queue Property] is used to define whether the [Semaphore][] functions as a [queuing semaphore][Queuing] or a [non-queuing semaphore][Non-Queuing]. + +If this property is set to `null`, then the [Semaphore][] will function as a [non-queuing semaphore][Non-Queuing]. +If given a value, the [Semaphore][] will function as a [queuing semaphore][Queuing] and configures how the [Semaphore's][Semaphore] queue should operate. + +| | | +|----------------|-----------------| +| Data Type | [QueueSettings][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | `null` | + +## Remarks + +### Create a SemaphoreSettings + +The following table shows some of the ways that `SemaphoreSettings` can be created. + +| Method | Example | Result | Editor Support | Notes | +|---------------------------------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-------------------------------------------------------------------------------------------------| +| Use a `SemaphoreSettings` constructor | `new SemaphoreSettings(new ScopeDefinition(ScopeOption.Current, ScopeOption.Current, ScopeOption.Current, ScopeOption.All), "SemaphoreA", 1, null)` | `{ "Scope": { "Tenant": ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.Current", "Flow": "ScopeOption.All" }, "Name": "SemaphoreA", "ConcurrencyLimit": 1, "Queue": null }` | Expression | Creates a new [SemaphoreSettings][] that can be used to configure the functions of a [Semaphore][]. | + +A [SemaphoreSettings][] can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|--------------------|-----------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `Scope` | `ScopeDefinition` | `new ScopeDefinition(ScopeOption.Current, ScopeOption.Current, ScopeOption.Current, ScopeOption.All)` | [Scope][Scope Property] defines the scope that the [Semaphore][] will operate in. | +| `Name` | `String` | `"SemaphoreA"` | [Name][Name Property] defines the name of the [Semaphore][]. | +| `ConcurrencyLimit` | `Int32` | `1` | [ConcurrencyLimit][ConcurrencyLimit Property] defines the maximum number of executions that can be inside the [Semaphore][] at one time. | +| `Queue` | `QueueSettings` | `null` | [Queue][Queue Property] defines the behaviour of the [Semaphore's][Semaphore] queue. | + +### Convert SemaphoreSettings to Text + +The following table shows some of the ways that a `SemaphoreSettings` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|------------------------------| +| Use `Convert Object To Json` block | where `Object` property has a value of `{ "Scope": { "Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.Current", "Flow": "ScopeOption.All" }, "Name": "SemaphoreA", "ConcurrencyLimit": 1, "Queue": null }` | `"{\r\n \"Scope\": {\r\n \"Tenant\": 1,\r\n \"System\": 1,\r\n \"Package\": 1,\r\n \"Flow\": 0\r\n },\r\n \"Name\": \"SemaphoreA\",\r\n \"ConcurrencyLimit\": 1,\r\n \"Queue\": null\r\n}"` | N/A | See [Convert Object To Json] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SemaphoreSettings`. +- The Literal Editor is available for [Input][] properties where the data type is `SemaphoreSettings`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SemaphoreSettings`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [QueueSettings][] +- [ScopeDefinition][] +- [String][] + +### Related Concepts + +- [What is a Semaphore?][Semaphore] + +### External Documentation + +None + +[Scope Property]: {{< ref "#scope" >}} +[Name Property]: {{< ref "#name" >}} +[ConcurrencyLimit Property]: {{< ref "#concurrencylimit" >}} +[Queue Property]: {{< ref "#queue" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Semaphore]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MainDoc" >}} +[Non-Queuing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.Non-Queuing" >}} +[Queuing]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.Queuing" >}} +[SemaphoreSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.SemaphoreSettings.MainDoc" >}} +[QueueSettings]: {{< url path="Cortex.Reference.DataTypes.Concurrency.Semaphores.QueueSettings.MainDoc" >}} +[MultipleConcurrencyLimits]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Concurrency.Semaphores.WhatIsASemaphore.MultipleConcurrencyLimits" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[ScopeDefinition]: {{< url path = "Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/data-types/conditional-logic/_index.md b/content/en/docs/2024.9/Reference/data-types/conditional-logic/_index.md new file mode 100644 index 000000000..306e1b7d4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/conditional-logic/_index.md @@ -0,0 +1,6 @@ +--- +title: "Conditional Logic" +linkTitle: "Conditional Logic" +description: "Data types used for working with conditional logic." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/conditional-logic/boolean.md b/content/en/docs/2024.9/Reference/data-types/conditional-logic/boolean.md new file mode 100644 index 000000000..32f8dc30d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/conditional-logic/boolean.md @@ -0,0 +1,99 @@ +--- +title: "Boolean" +linkTitle: "Boolean" +description: "Used to represent a logical value of `true` or `false`." +--- + +# {{% param title %}} + +

(System.Boolean)

+ +## Summary + +The `Boolean` data type is used to represent a logical value of `true` or `false`. + +| | | +|-|-| +| **Category:** | Conditional Logic | +| **Name:** | `Boolean` | +| **Full Name:** | `System.Boolean` | +| **Alias:** | `bool` | +| **Description:** | A logical value of `true` or `false`. | +| **Size:** | `1` bit | +| **Default Value:** | `false` | +| **Can be used as:** | `Nullable`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a Boolean + +The following table shows some of the ways that a `Boolean` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `Boolean` literal | `true` | `true` | Literal, Expression | True | +| | `false` | `false` | Literal, Expression | False | +| Use a `Boolean` expression | `1 == 1` | `true` | Expression | Uses equals operator | +| | `1 != 1` | `false` | Expression | Uses not equals operator | +| | `1 > 0` | `true` | Expression | Uses greater than operator | +| | `1 < 0` | `false` | Expression | Uses less than operator | +| | `1 >= 0` | `true` | Expression | Uses greater than or equals operator | +| | `1 <= 0` | `false` | Expression | Uses less than or equals operator | +| | `true && false` | `false` | Expression | Uses logical AND operator | +| | `true \|\| false` | `true` | Expression | Uses logical OR operator | +| | `!(true \|\| false)` | `false` | Expression | Uses logical NOT operator | +| | `Boolean.Parse("true")`| `true` | Expression | Attempts to parse text and convert it to a `Boolean` value. See [Boolean.Parse][] | +| | `Convert.ToBoolean("true")` | `true` | Expression | Attempts to convert text to a `Boolean` value. See [Convert.ToBoolean][] | + +### Convert Boolean to Text + +The following table shows some of the ways that a `Boolean` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `true.ToString()` | `"True"` | Expression | See [Boolean.ToString][] | +| | `($)BooleanVariable.ToString()` where `($)BooleanVariable` has a value of `true` | `"True"` | Expression | See [Boolean.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(true)` | `"True"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)BooleanVariable)` where `($)BooleanVariable` has a value of `true` | `"True"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `true` | `"True"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `true` | `"true"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Boolean`. +* The Literal Editor is available for [Input][] properties where the data type is `Boolean`. + * Expression syntax is not supported within the Literal Editor for the `Boolean` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Boolean`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +None + +### Related Concepts + +None + +### External Documentation + +* [System.Boolean][] + +[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" >}} + +[Convert.ToBoolean]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToBoolean" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Boolean]: {{< url path="MSDocs.DotNet.Api.System.Boolean.MainDoc" >}} +[Boolean.Parse]: {{< url path="MSDocs.DotNet.Api.System.Boolean.Parse" >}} +[Boolean.ToString]: {{< url path="MSDocs.DotNet.Api.System.Boolean.ToString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/credentials/_index.md b/content/en/docs/2024.9/Reference/data-types/credentials/_index.md new file mode 100644 index 000000000..536b77101 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/credentials/_index.md @@ -0,0 +1,6 @@ +--- +title: "Credentials" +linkTitle: "Credentials" +description: "Data types used for working with credentials." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/credentials/iusercredentials.md b/content/en/docs/2024.9/Reference/data-types/credentials/iusercredentials.md new file mode 100644 index 000000000..f0c276ca3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/credentials/iusercredentials.md @@ -0,0 +1,83 @@ +--- +title: "IUserCredentials" +linkTitle: "IUserCredentials" +description: "Any data type representing password authentication credentials required to authenticate with a domain or server." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Credentials.IUserCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type representing password authentication credentials required to authenticate with a domain or server. + +| | | +|-|-| +| **Category:** | Credentials | +| **Name:** | `IUserCredentials` | +| **Full Name:** | `Cortex.DataTypes.Credentials.IUserCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type representing password authentication credentials required to authenticate with a domain or server. | +| **Default Value:** | `null` | +| **Can be used as:** | `IUserCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `IUserCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `IUserCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `IUserCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [BasicEmailSessionDetails][] +- [EmailCredentials][] +- [EmailUserCredentials][] +- [EncryptableText][] +- [EncryptedText][] +- [HttpCredentials][] +- [HttpUserCredentials][] +- [IEmailCredentials][] +- [IHttpCredentials][] +- [ISshCredentials][] +- [SshCredentials][] +- [SshUserCredentials][] +- [UserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[BasicEmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.MainDoc" >}} +[IEmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.IEmailCredentials.MainDoc" >}} +[EmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.EmailCredentials.MainDoc" >}} +[EmailUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.EmailUserCredentials.MainDoc" >}} +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpUserCredentials.MainDoc" >}} +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} +[SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} +[SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/credentials/logontype.md b/content/en/docs/2024.9/Reference/data-types/credentials/logontype.md new file mode 100644 index 000000000..b71cd6f70 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/credentials/logontype.md @@ -0,0 +1,173 @@ +--- +title: "LogonType" +linkTitle: "LogonType" +description: "Used to represent the Logon type used for the UserCredentials." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Credentials.LogonType)

+ +## Summary + +The `LogonType` data type is used to represent the type of logon method to use to authenticate a user. + +`LogonType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------------------------------| +| **Category:** | Credentials | +| **Name:** | `LogonType` | +| **Full Name:** | `Cortex.DataTypes.Credentials.LogonType` | +| **Alias:** | N/A | +| **Description:** | Used to represent the type of logon method to use to authenticate a user. | +| **Default Value:** | `LogonType.Network` | +| **Can be used as:** | `LogonType`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)LogonType.Network` or `(System.Int16)LogonType.Network` or `(short)LogonType.Network`) | +| | `Int32` (e.g. `(Int32)LogonType.Network` or `(System.Int32)LogonType.Network` or `(int)LogonType.Network`) | +| | `Int64` (e.g. `(Int64)LogonType.Network` or `(System.Int64)LogonType.Network` or `(long)LogonType.Network`) | +| | `Single` (e.g. `(Single)LogonType.Network` or `(System.Single)LogonType.Network` or `(float)LogonType.Network`) | +| | `Double` (e.g. `(Double)LogonType.Network` or `(System.Double)LogonType.Network` or `(double)LogonType.Network`) | + +## Values + +### Network + +| | | +|------------|----------------------------| +| **Name:** | Network | +| **Value:** | [Int32][] with value `3` | +| **Notes:** | Represents a network logon. This should be used in most cases, including when connecting to a local database as a Windows user. If connecting to a remote database as a Windows user, [NewCredentials][] should be used. | + +### NetworkCleartext + +| | | +|------------|----------------------------| +| **Name:** | NetworkCleartext | +| **Value:** | [Int32][] with value `8` | +| **Notes:** | Represents a network logon. This differs from [Network][] as the user's password will be passed as cleartext. This should be used when authenticating with IIS using Basic Auth, and Windows PowerShell with CredSSP. | + +### NewCredentials + +| | | +|------------|----------------------------| +| **Name:** | NewCredentials | +| **Value:** | [Int32][] with value `9` | +| **Notes:** | Represents a clone of the user's current logon. For local operations, it uses the same local identity. For network operations, it uses the identity of the credentials supplied. This should be used when authenticating against a remote database as a Windows User. If connecting to a local database as a Windows user, [Network][] should be used. | + +## Remarks + +### Create LogonType + +The following table shows some of the ways that `LogonType` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `LogonType` expression | `LogonType.Network` | `LogonType.Network`| Expression | | +| | `LogonType.NetworkCleartext` | `LogonType.NetworkCleartext` | Expression | | +| | `LogonType.NewCredentials` | `LogonType.NewCredentials` | Expression | | +| Use [Explicit Casting][] | `(LogonType)3` | `LogonType.Network`| Expression | | +| | `(LogonType)8` | `LogonType.NetworkCleartext` | Expression | | +| | `(LogonType)9` | `LogonType.NewCredentials` | Expression | | +| Use `Enum.Parse` | `(LogonType)Enum.Parse(typeof(LogonType), "Network")` | `LogonType.Network`| Expression | Parses `"Network"` and converts it to `LogonType.Network`. See [Enum.Parse][] | +| | `(LogonType)Enum.Parse(typeof(LogonType), "NetworkCleartext")` | `LogonType.NetworkCleartext`| Expression | Parses `"NetworkCleartext"` and converts it to `LogonType.NetworkCleartext`. See [Enum.Parse][] | +| | `(LogonType)Enum.Parse(typeof(LogonType), "NewCredentials")` | `LogonType.NewCredentials`| Expression | Parses `"NewCredentials"` and converts it to `LogonType.NewCredentials`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(LogonType)Enum.ToObject(typeof(LogonType), 3)` | `LogonType.Network`| Expression | Converts `3` to `LogonType.Network` value. See [Enum.ToObject][] | +| | `(LogonType)Enum.ToObject(typeof(LogonType), 8)` | `LogonType.NetworkCleartext` | Expression | Converts `8` to `LogonType.NetworkCleartext` value. See [Enum.ToObject][] | +| | `(LogonType)Enum.ToObject(typeof(LogonType), 9)` | `LogonType.NewCredentials` | Expression | Converts `9` to `LogonType.NewCredentials` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert LogonType to Text + +The following table shows some of the ways that a `LogonType` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `LogonType.Network.ToString()` | `"Network"` | Expression | Converts `LogonType.Network` to `"Network"`. See [Enum.ToString][] | +| | `LogonType.NetworkCleartext.ToString()` | `"NetworkCleartext"` | Expression | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Enum.ToString][] | +| | `LogonType.NewCredentials.ToString()` | `"NewCredentials"` | Expression | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(LogonType.Network)` | `"Network"` | Expression | Converts `LogonType.Network` to `"Network"`. See [Convert.ToString][] | +| | `Convert.ToString(LogonType.NetworkCleartext)` | `"NetworkCleartext"` | Expression | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Convert.ToString][] | +| | `Convert.ToString(LogonType.NewCredentials)` | `"NewCredentials"` | Expression | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `LogonType.Network` | `"Network"` | N/A | Converts `LogonType.Network` to `"Network"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `LogonType.NetworkCleartext` | `"NetworkCleartext"` | N/A | Converts `LogonType.NetworkCleartext` to `"NetworkCleartext"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `LogonType.NewCredentials` | `"NewCredentials"` | N/A | Converts `LogonType.NewCredentials` to `"NewCredentials"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `LogonType.Network` | `"3"` | N/A | Converts `LogonType.Network` to `"3"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `LogonType.NetworkCleartext` | `"8"` | N/A | Converts `LogonType.NetworkCleartext` to `"8"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `LogonType.NewCredentials` | `"9"` | N/A | Converts `LogonType.NewCredentials` to `"9"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert LogonType to a Number + +The following table shows some of the ways that a `LogonType` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)LogonType.Network` | `3` | Expression | [Casts][Explicit Casting] `LogonType.Network` to `3` | +| | `(Int32)LogonType.NetworkCleartext` | `8` | Expression | [Casts][Explicit Casting] `LogonType.NetworkCleartext` to `8` | +| | `(Int32)LogonType.NewCredentials` | `9` | Expression | [Casts][Explicit Casting] `LogonType.NewCredentials` to `9` | +| Use `Convert.ToInt32` | `Convert.ToInt32(LogonType.Network)` | `3` | Expression | Converts `LogonType.Network` to `3`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(LogonType.NetworkCleartext)` | `8` | Expression | Converts `LogonType.NetworkCleartext` to `8`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(LogonType.NewCredentials)` | `9` | Expression | Converts `LogonType.NewCredentials` to `9`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `LogonType`. +- The Literal Editor is available for [Input][] properties where the data type is `LogonType`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `LogonType`. + +### Known Limitations + +- When [LogonType][] is set to `LogonType.NewCredentials` and trying to connect to a localhost database, it will not recognise the UserCredentials. To fix this use `LogonType.Network` as the [LogonType][]. +- When [LogonType][] is set to `LogonType.Network` and trying to connect to a remote database, it will not recognise the UserCredentials. To fix this use `LogonType.NewCredentials` as the [LogonType][]. + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [UserCredentials][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [LogonTypes][] +- [System.Enum][] + +[Network]: {{< ref "#network" >}} +[NewCredentials]: {{< ref "#newcredentials" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[LogonTypes]: {{< url path="MSDocs.Windows.WindowsServer.LogonTypes" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/credentials/usercredentials.md b/content/en/docs/2024.9/Reference/data-types/credentials/usercredentials.md new file mode 100644 index 000000000..1a0a5b4ba --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/credentials/usercredentials.md @@ -0,0 +1,173 @@ +--- +title: "UserCredentials" +linkTitle: "UserCredentials" +description: "Used to represent details required to authenticate with a domain or server." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Credentials.UserCredentials)

+ +## Summary + +The `UserCredentials` data type is used to represent details required to authenticate with a domain or server. + +| | | +|-|-| +| **Category:** | Credentials | +| **Name:** | `UserCredentials` | +| **Full Name:** | `Cortex.DataTypes.Credentials.UserCredentials` | +| **Alias:** | N/A | +| **Description:** | Details required to authenticate with a domain or server. | +| **Default Value:** | `null` | +| **Can be used as:** | `EmailUserCredentials`, `EmailCredentials`, `IEmailCredentials`, `HttpUserCredentials`, `HttpCredentials`, `IHttpCredentials`, `SshUserCredentials`, `SshCredentials`, `ISshCredentials`, `UserCredentials`, `IUserCredentials`, `NetworkCredential`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Domain + +The Domain is used to define the domain or server to authenticate with. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +Whether or not the Domain is required is dependent on the block being used: + +- [Send Email Using SMTP Server Block][Send Email Using SMTP Server Block Setting Credentials] +- [Send Email Using Gmail Block][Send Email Using Gmail Block Setting Credentials] + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### Username + +The Username is used to define the user to authenticate as. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### Password + +The Password is used to define the password of the user to authenticate as. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +### LogonType + +The LogonType is used to define what type of logon method to use to authenticate the user. This property is a [LogonType][] which is an enum. + +| | | +|--------------------|---------------------------| +| Data Type | [LogonType][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [LogonType][] with value `LogonType.Network` | + +## Remarks + +### Create a UserCredentials + +The following table shows some of the ways that `UserCredentials` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `UserCredentials` constructor | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword")` | `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain specified | +| | `new UserCredentials(username: "username", password: "encryptedPassword")` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword"}` | Expression | Domain not specified | +| | `new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword", logonType: LogonType.Network)` | `{"Domain": "domain", "Username": "username", "encryptedPassword", "LogonType": "LogonType.Network"}` | Expression | Domain and LogonType specified | +| | `new UserCredentials(username: "username", password: "encryptedPassword", logonType: LogonType.Network)` | `{"Domain": null, "Username": "username", "Password": "encryptedPassword", "LogonType": "LogonType.Network"}` | Expression | Domain and LogonType not specified | + +A `UserCredentials` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Domain` | `EncryptableText` | `"domain"` | [Domain][Domain Property] defines the domain or server to authenticate with. | +| `Username` | `EncryptableText` | `"username"` | [Username][Username Property] defines the user to authenticate as. | +| `Password` | `EncryptedText` | `"encryptedPassword"` | [Password][Password Property] defines the password of the user to authenticate as. | +| `LogonType` | `LogonType` | `LogonType.Network` | [LogonType][LogonType Property] defines what type of logon method to use to authenticate the user. | + +### Convert UserCredentials to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Domain": "domain", "Username": "username", "Password": "encryptedPassword", "LogonType": "LogonType.Network"}` | `"{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\",\r\n \"LogonType\": 3\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `UserCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `UserCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `UserCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [BasicEmailSessionDetails][] +- [EmailCredentials][] +- [EmailUserCredentials][] +- [EncryptableText][] +- [EncryptedText][] +- [HttpCredentials][] +- [HttpUserCredentials][] +- [IEmailCredentials][] +- [IHttpCredentials][] +- [ISshCredentials][] +- [SshCredentials][] +- [SshUserCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +- [NetworkCredential][] + +[Domain Property]: {{< ref "#domain" >}} +[Username Property]: {{< ref "#username" >}} +[Password Property]: {{< ref "#password" >}} +[LogonType Property]: {{< ref "#logontype" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[BasicEmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.MainDoc" >}} +[IEmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.IEmailCredentials.MainDoc" >}} +[EmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.EmailCredentials.MainDoc" >}} +[EmailUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.EmailUserCredentials.MainDoc" >}} +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpUserCredentials.MainDoc" >}} +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} +[SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} +[SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} +[LogonType]: {{< url path="Cortex.Reference.DataTypes.Credentials.LogonType.MainDoc" >}} + +[NetworkCredential]: {{< url path="MSDocs.DotNet.Api.System.Net.NetworkCredential" >}} + +[Send Email Using SMTP Server Block Setting Credentials]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.SettingCredentials" >}} +[Send Email Using Gmail Block Setting Credentials]: {{< url path="Cortex.Reference.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmail.SettingCredentials" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/_index.md b/content/en/docs/2024.9/Reference/data-types/data/_index.md new file mode 100644 index 000000000..d7939208d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/_index.md @@ -0,0 +1,6 @@ +--- +title: "Data" +linkTitle: "Data" +description: "Data types used for working with data sources such as SQL Server." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/data/command.md b/content/en/docs/2024.9/Reference/data-types/data/command.md new file mode 100644 index 000000000..08f6a6c0a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/command.md @@ -0,0 +1,156 @@ +--- +title: "Command" +linkTitle: "Command" +description: "Defines a single statement that can be run against a data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.Command)

+ +## Summary + +A `Command` data type is used to define a single [statement][Statements] that can be run against a data source. The statement can be [parameterised][Parameterised Commands], which is recommended to prevent [SQL Injection][]. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `Command` | +| **Full Name:** | `Cortex.DataTypes.Data.Command` | +| **Alias:** | N/A | +| **Description:** | Defines a single statement that can be run against a data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `DataCommand`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Command Text + +The Command Text is used to define a single [statement][Statements] that will be run against the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Parameters + +Parameters are used to pass information to the [statement][Statements] that will be run against the data source. + +It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +For more information see [Parameterised Commands][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `true` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +## Remarks + +### Create a Command + +The following table shows some of the ways that a `Command` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Command` constructor | `new Command("SELECT * FROM Table", null)` | `{CommandText: "SELECT * FROM Table", Parameters: null}` | Expression | | +| | `new Command("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3})` | `{"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}}` | Expression | It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] | + +A `Command` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `CommandText`| `EncryptableText`| `$@"SELECT * FROM Table WHERE Id < @SelectParameter"` | The command that will be executed or queried against the data source. | +| `Parameters`| `dynamic`| `new {SelectParameter = 3}` | The parameters that are used within a [Parameterised Command][Parameterised Commands]. | + +### Convert Command to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)Command.ToString()` | `"Cortex.DataTypes.Data.Command"` | Expression | ToString will return the Full Name of the Command Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"Cortex.DataTypes.Data.Command"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +The `@` symbol denotes a parameter within the [CommandText][] (e.g. `"SELECT * FROM Table WHERE Name = @Parameter"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +For more information see [Parameterised Commands][Block: Parameterised Commands]. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Command`. +* The Literal Editor is not available for [Input][] properties where the data type is `Command`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Command`. + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `Command`, then its Full Name will be returned; instead of a representation of the data within the `Command`. + +In future this limitation may be removed. + +#### Block Statements Incompatible (Oracle Only) + +Using an [OracleBlockStatement][] in the [CommandText][] will throw a [Command Exception][CommandExceptionIncompatibleStatementType]. You must use either a [QueryCommand][] or [NonQueryCommand][] instead. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [OracleBlockStatement][] +* [SQL Injection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Statements]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.Statements" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} +[CommandExceptionIncompatibleStatementType]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.IncompatibleStatementType" >}} +[ConnectionDetailsProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ConnectionDetailsProperty" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} +[SQL Injection]: {{< url path="W3.SqlInjection" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/commands.md b/content/en/docs/2024.9/Reference/data-types/data/commands.md new file mode 100644 index 000000000..55739670e --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/commands.md @@ -0,0 +1,156 @@ +--- +title: "Commands" +linkTitle: "Commands" +description: "Holds the information for parsing a command, running multiple query and non query commands against a data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.Commands)

+ +## Summary + +A `Commands` data type is used to define single or multiple [statements][Statements] that can be run against a data source. Statements can be [parameterised][Parameterised Commands], which is recommended to prevent [SQL Injection][]. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `Commands` | +| **Full Name:** | `Cortex.DataTypes.Data.Commands` | +| **Alias:** | N/A | +| **Description:** | Defines single or multiple statements that can be run against a data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `DataCommand`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Command Text + +The Command Text is used to define single or multiple [statements][Statements] that will be run against the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Parameters + +Parameters are used to pass information to the single or multiple [statements][Statements] that will be run against the data source. + +It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +For more information see [Parameterised Commands][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `true` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +## Remarks + +### Create a Commands + +The following table shows some of the ways that a `Commands` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Commands` constructor | `new Commands("SELECT * FROM Table", null)` | `{CommandText: "SELECT * FROM Table", Parameters: null}` | Expression | | +| | `new Commands("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3})` | `{"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}}` | Expression | It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] | + +A `Commands` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `CommandText`| `EncryptableText`| `$@"SELECT * FROM Table WHERE Id < @SelectParameter"` | The command that will be executed or queried against the data source. | +| `Parameters`| `dynamic`| `new {SelectParameter = 3}` | The parameters that are used within a [Parameterised Command][Parameterised Commands]. | + +### Convert Commands to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)Commands.ToString()` | `"Cortex.DataTypes.Data.Commands"` | Expression | ToString will return the Full Name of the Commands Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"Cortex.DataTypes.Data.Commands"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +The `@` symbol denotes a parameter within the [CommandText][] (e.g. `"SELECT * FROM Table WHERE Name = @Parameter"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +For more information see [Parameterised Commands][Block: Parameterised Commands]. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Commands`. +* The Literal Editor is available for [Input][] properties where the data type is `Commands`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Commands`. + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `Commands`, then its Full Name will be returned; instead of a representation of the data within the `Commands`. + +In future this limitation may be removed. + +#### Block Statements Incompatible (Oracle Only) + +Using an [OracleBlockStatement][] in the [CommandText][] will throw a [Command Exception][CommandExceptionIncompatibleStatementType]. You must use either a [QueryCommand][] or [NonQueryCommand][] instead. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Command][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [OracleBlockStatement][] +* [SQL Injection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Statements]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.QueryStatements" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[ConnectionDetailsProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ConnectionDetailsProperty" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} +[CommandExceptionIncompatibleStatementType]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.IncompatibleStatementType" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} +[SQL Injection]: {{< url path="W3.SqlInjection" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/connectiondetails.md b/content/en/docs/2024.9/Reference/data-types/data/connectiondetails.md new file mode 100644 index 000000000..0e2e91bbe --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/connectiondetails.md @@ -0,0 +1,76 @@ +--- +title: "ConnectionDetails" +linkTitle: "ConnectionDetails" +description: "Any data type representing configuration for establishing and maintaining a connection to a data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.ConnectionDetails)

+ +## Summary + +Any data type representing configuration for establishing and maintaining a connection to a data source. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `ConnectionDetails` | +| **Full Name:** | `Cortex.DataTypes.Data.ConnectionDetails` | +| **Alias:** | N/A | +| **Description:** | Any data type representing configuration for establishing and maintaining a connection to a data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common ConnectionDetails Data Types + +Any of the following data types can be used where a `ConnectionDetails` is required: + +- [OdbcConnectionDetails][] +- [OracleConnectionDetails][] +- [SqlServerConnectionDetails][] + +### Create a ConnectionDetails + +For some of the ways that a `ConnectionDetails` can be created, please see each of the `ConnectionDetails` data types: + +- [OdbcConnectionDetails][] +- [OracleConnectionDetails][] +- [SqlServerConnectionDetails][] + +### Convert ConnectionDetails to Text + +For some of the ways that a `ConnectionDetails` can be converted to text, please see each of the `ConnectionDetails` data types: + +- [OdbcConnectionDetails][] +- [OracleConnectionDetails][] +- [SqlServerConnectionDetails][] + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [OdbcConnectionDetails][] +- [OracleConnectionDetails][] +- [SqlServerConnectionDetails][] + +### Related Concepts + +- [Working with Data Sources][] + +### External Documentation + +None + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/datacommand.md b/content/en/docs/2024.9/Reference/data-types/data/datacommand.md new file mode 100644 index 000000000..bef4eefde --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/datacommand.md @@ -0,0 +1,140 @@ +--- +title: "DataCommand" +linkTitle: "DataCommand" +description: "Any data type representing configuration for data source commands." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.DataCommand)

+ +## Summary + +Any data type representing configuration for data source commands. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `DataCommand` | +| **Full Name:** | `Cortex.DataTypes.Data.DataCommand` | +| **Alias:** | N/A | +| **Description:** | Any data type representing configuration for data source commands. | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Command Text + +The Command Text is used to create the command that will be run against the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Parameters + +Parameters are used to pass information to the command that will be run against the data source. + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +For more information see [Parameterised Commands][Parameterised Commands] + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `true` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +## Remarks + +### Most Common DataCommand Data Types + +Any of the following data types can be used where a `DataCommand` is required: + +* [Command][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Create a DataCommand + +For some of the ways that a `DataCommand` can be created, please see each of the `DataCommand` data types: + +* [Command][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Convert DataCommand to Text + +For some of the ways that a `DataCommand` can be converted to text, please see each of the `DataCommand` data types: + +* [Command][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +The `@` symbol denotes a parameter within the [CommandText][] (e.g. `"SELECT * FROM Table WHERE Name = @Parameter"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +For more information see [Parameterised Commands][Block: Parameterised Commands]. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `DataCommand`. +* The Literal Editor is available for [Input][] properties where the data type is `DataCommand`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `DataCommand`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +* [Command][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [SQL Injection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} + +[SQL Injection]: {{< url path="W3.SqlInjection" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/datacommanderrorcode.md b/content/en/docs/2024.9/Reference/data-types/data/datacommanderrorcode.md new file mode 100644 index 000000000..3b8804143 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/datacommanderrorcode.md @@ -0,0 +1,228 @@ +--- +title: "DataCommandErrorCode" +linkTitle: "DataCommandErrorCode" +description: "Used to represent an error code explaining the reason an `CommandException` occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.DataCommandErrorCode)

+ +## Summary + +The `DataCommandErrorCode` data type is used to represent an error code explaining the reason a [CommandException][] occurred. For more information on the exception itself, see [CommandException][]. + +`DataCommandErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `DataCommandErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Data.DataCommandErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [CommandException][] occurred. | +| **Size:** | `4` bytes | +| **Default Value:** | `(DataCommandErrorCode)0` | +| **Can be used as:** | `DataCommandErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)DataCommandErrorCode.Connection` or `(System.Int16)DataCommandErrorCode.Connection` or `(short)DataCommandErrorCode.Connection`) | +| | `Int32` (e.g. `(Int32)DataCommandErrorCode.Connection` or `(System.Int32)DataCommandErrorCode.Connection` or `(int)DataCommandErrorCode.Connection`) | +| | `Int64` (e.g. `(Int64)DataCommandErrorCode.Connection` or `(System.Int64)DataCommandErrorCode.Connection` or `(long)DataCommandErrorCode.Connection`) | +| | `Single` (e.g. `(Single)DataCommandErrorCode.Connection` or `(System.Single)DataCommandErrorCode.Connection` or `(float)DataCommandErrorCode.Connection`) | +| | `Double` (e.g. `(Double)DataCommandErrorCode.Connection` or `(System.Double)DataCommandErrorCode.Connection` or `(double)DataCommandErrorCode.Connection`) | + +## Values + +### Connection {#1000} + +| | | +|-|-| +| **Name:** | Connection | +| **Value:** | [Int32][] with value `1000` | +| **Notes:** | Used when a [CommandException][] occured when the connection to the data source failed. | + +### Statement {#2000} + +| | | +|-|-| +| **Name:** | Statement | +| **Value:** | [Int32][] with value `2000` | +| **Notes:** | Used when a [CommandException][] occured due to the statement(s) being passed into the [Command Property][CommandProperty] could not be parsed. | + +### IncompatibleStatementType {#2001} + +| | | +|-|-| +| **Name:** | IncompatibleStatementType | +| **Value:** | [Int32][] with value `2001` | +| **Notes:** | Used when a [CommandException][] occured due to an [OracleBlockStatement][] being passed into the [Command Property][CommandProperty] when using a [Command][] or [Commands][] data type. | + +### MultipleStatements {#2002} + +| | | +|-|-| +| **Name:** | MultipleStatements | +| **Value:** | [Int32][] with value `2002` | +| **Notes:** | Used when a [CommandException][] occured due to multiple statements being passed into the [Command Property][CommandProperty] when using a [Command][] data type. | + +### Runtime {#3000} + +| | | +|-|-| +| **Name:** | Runtime | +| **Value:** | [Int32][] with value `3000` | +| **Notes:** | Used when a [CommandException][] occured due to an error during the execution of the statement(s). | + +## Remarks + +### Create a DataCommandErrorCode + +The following table shows some of the ways that `DataCommandErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `DataCommandErrorCode` expression | `DataCommandErrorCode.Connection` | `DataCommandErrorCode.Connection`| Expression | Indicates a [CommandException][] occured when the connection to the data source failed | +| | `DataCommandErrorCode.Statement` | `DataCommandErrorCode.Statement`| Expression | Indicates a [CommandException][] occured due to the statement(s) being passed into the [Command Property][CommandProperty] could not be parsed | +| | `DataCommandErrorCode.IncompatibleStatementType` | `DataCommandErrorCode.IncompatibleStatementType`| Expression | Indicates a [CommandException][] occured due to an [OracleBlockStatement][] being passed into the [Command Property][CommandProperty] when using a [Command][] or [Commands][] data type | +| | `DataCommandErrorCode.MultipleStatements` | `DataCommandErrorCode.MultipleStatements`| Expression | Indicates a [CommandException][] occured due to multiple statements being passed into the [Command Property][CommandProperty] when using a [Command][] data type | +| | `DataCommandErrorCode.Runtime` | `DataCommandErrorCode.Runtime`| Expression | Indicates a [CommandException][] occured due to an error during the execution of the statement(s) | +| Use [Explicit Casting][] | `(DataCommandErrorCode)1000` | `DataCommandErrorCode.Connection`| Expression | Indicates a [CommandException][] occured when the connection to the data source failed | +| | `(DataCommandErrorCode)2000` | `DataCommandErrorCode.Statement`| Expression | Indicates a [CommandException][] occured due to the statement(s) being passed into the [Command Property][CommandProperty] could not be parsed | +| | `(DataCommandErrorCode)2001` | `DataCommandErrorCode.IncompatibleStatementType`| Expression | Indicates a [CommandException][] occured due to an [OracleBlockStatement][] being passed into the [Command Property][CommandProperty] when using a [Command][] or [Commands][] data type | +| | `(DataCommandErrorCode)2002` | `DataCommandErrorCode.MultipleStatements`| Expression | Indicates a [CommandException][] occured due to multiple statements being passed into the [Command Property][CommandProperty] when using a [Command][] data type | +| | `(DataCommandErrorCode)3000` | `DataCommandErrorCode.Runtime`| Expression | Indicates a [CommandException][] occured due to an error during the execution of the statement(s) | +| Use `Enum.Parse` | `(DataCommandErrorCode)Enum.Parse(typeof(DataCommandErrorCode), "Connection")` | `DataCommandErrorCode.Connection`| Expression | Parses `"Connection"` and converts it to `DataCommandErrorCode.Connection`. See [Enum.Parse][] | +| | `(DataCommandErrorCode)Enum.Parse(typeof(DataCommandErrorCode), "Statement")` | `DataCommandErrorCode.Statement`| Expression | Parses `"Statement"` and converts it to `DataCommandErrorCode.Statement`. See [Enum.Parse][] | +| | `(DataCommandErrorCode)Enum.Parse(typeof(DataCommandErrorCode), "IncompatibleStatementType")` | `DataCommandErrorCode.IncompatibleStatementType`| Expression | Parses `"IncompatibleStatementType"` and converts it to `DataCommandErrorCode.IncompatibleStatementType`. See [Enum.Parse][] | +| | `(DataCommandErrorCode)Enum.Parse(typeof(DataCommandErrorCode), "MultipleStatements")` | `DataCommandErrorCode.MultipleStatements`| Expression | Parses `"MultipleStatements"` and converts it to `DataCommandErrorCode.MultipleStatements`. See [Enum.Parse][] | +| | `(DataCommandErrorCode)Enum.Parse(typeof(DataCommandErrorCode), "Runtime")` | `DataCommandErrorCode.Runtime`| Expression | Parses `"Runtime"` and converts it to `DataCommandErrorCode.Runtime`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(DataCommandErrorCode)Enum.ToObject(typeof(DataCommandErrorCode), 1000)` | `DataCommandErrorCode.Connection`| Expression | Converts `1000` to `DataCommandErrorCode.Connection` value. See [Enum.ToObject][] | +| | `(DataCommandErrorCode)Enum.ToObject(typeof(DataCommandErrorCode), 2000)` | `DataCommandErrorCode.Statement`| Expression | Converts `2000` to `DataCommandErrorCode.Statement` value. See [Enum.ToObject][] | +| | `(DataCommandErrorCode)Enum.ToObject(typeof(DataCommandErrorCode), 2001)` | `DataCommandErrorCode.IncompatibleStatementType`| Expression | Converts `2001` to `DataCommandErrorCode.IncompatibleStatementType` value. See [Enum.ToObject][] | +| | `(DataCommandErrorCode)Enum.ToObject(typeof(DataCommandErrorCode), 2002)` | `DataCommandErrorCode.MultipleStatements`| Expression | Converts `2002` to `DataCommandErrorCode.MultipleStatements` value. See [Enum.ToObject][] | +| | `(DataCommandErrorCode)Enum.ToObject(typeof(DataCommandErrorCode), 3000)` | `DataCommandErrorCode.Runtime`| Expression | Converts `3000` to `DataCommandErrorCode.Runtime` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert DataCommandErrorCode to Text + +The following table shows some of the ways that a `DataCommandErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `DataCommandErrorCode.Connection.ToString()` | `"Connection"` | Expression | Converts `DataCommandErrorCode.Connection` to `"Connection"`. See [Enum.ToString][] | +| | `DataCommandErrorCode.Statement.ToString()` | `"Statement"` | Expression | Converts `DataCommandErrorCode.Statement` to `"Statement"`. See [Enum.ToString][] | +| | `DataCommandErrorCode.IncompatibleStatementType.ToString()` | `"IncompatibleStatementType"` | Expression | Converts `DataCommandErrorCode.IncompatibleStatementType` to `"IncompatibleStatementType"`. See [Enum.ToString][] | +| | `DataCommandErrorCode.MultipleStatements.ToString()` | `"MultipleStatements"` | Expression | Converts `DataCommandErrorCode.MultipleStatements` to `"MultipleStatements"`. See [Enum.ToString][] | +| | `DataCommandErrorCode.Runtime.ToString()` | `"Runtime"` | Expression | Converts `DataCommandErrorCode.Runtime` to `"Runtime"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(DataCommandErrorCode.Connection)` | `"Connection"` | Expression | Converts `DataCommandErrorCode.Connection` to `"Connection"`. See [Convert.ToString][] | +| | `Convert.ToString(DataCommandErrorCode.Statement)` | `"Statement"` | Expression | Converts `DataCommandErrorCode.Statement` to `"Statement"`. See [Convert.ToString][] | +| | `Convert.ToString(DataCommandErrorCode.IncompatibleStatementType)` | `"IncompatibleStatementType"` | Expression | Converts `DataCommandErrorCode.IncompatibleStatementType` to `"IncompatibleStatementType"`. See [Convert.ToString][] | +| | `Convert.ToString(DataCommandErrorCode.MultipleStatements)` | `"MultipleStatements"` | Expression | Converts `DataCommandErrorCode.MultipleStatements` to `"MultipleStatements"`. See [Convert.ToString][] | +| | `Convert.ToString(DataCommandErrorCode.Runtime)` | `"Runtime"` | Expression | Converts `DataCommandErrorCode.Runtime` to `"Runtime"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `DataCommandErrorCode.Connection` | `"Connection"` | N/A | Converts `DataCommandErrorCode.Connection` to `"Connection"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DataCommandErrorCode.Statement` | `"Statement"` | N/A | Converts `DataCommandErrorCode.Statement` to `"Statement"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DataCommandErrorCode.IncompatibleStatementType` | `"IncompatibleStatementType"` | N/A | Converts `DataCommandErrorCode.IncompatibleStatementType` to `"IncompatibleStatementType"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DataCommandErrorCode.MultipleStatements` | `"MultipleStatements"` | N/A | Converts `DataCommandErrorCode.MultipleStatements` to `"MultipleStatements"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DataCommandErrorCode.Runtime` | `"Runtime"` | N/A | Converts `DataCommandErrorCode.Runtime` to `"Runtime"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `DataCommandErrorCode.Connection` | `"1000"` | N/A | Converts `DataCommandErrorCode.Connection` to `"1000"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DataCommandErrorCode.Statement` | `"2000"` | N/A | Converts `DataCommandErrorCode.Statement` to `"2000"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DataCommandErrorCode.IncompatibleStatementType` | `"2001"` | N/A | Converts `DataCommandErrorCode.IncompatibleStatementType` to `"2001"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DataCommandErrorCode.MultipleStatements` | `"2002"` | N/A | Converts `DataCommandErrorCode.MultipleStatements` to `"2002"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DataCommandErrorCode.Runtime` | `"3000"` | N/A | Converts `DataCommandErrorCode.Runtime` to `"3000"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert DataCommandErrorCode to a Number + +The following table shows some of the ways that a `DataCommandErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)DataCommandErrorCode.Connection` | `1000` | Expression | [Casts][Explicit Casting] `DataCommandErrorCode.Connection` to `1000` | +| | `(Int32)DataCommandErrorCode.Statement` | `2000` | Expression | [Casts][Explicit Casting] `DataCommandErrorCode.Statement` to `2000` | +| | `(Int32)DataCommandErrorCode.IncompatibleStatementType` | `2001` | Expression | [Casts][Explicit Casting] `DataCommandErrorCode.IncompatibleStatementType` to `2001` | +| | `(Int32)DataCommandErrorCode.MultipleStatements` | `2002` | Expression | [Casts][Explicit Casting] `DataCommandErrorCode.MultipleStatements` to `2002` | +| | `(Int32)DataCommandErrorCode.Runtime` | `3000` | Expression | [Casts][Explicit Casting] `DataCommandErrorCode.Runtime` to `3000` | +| Use `Convert.ToInt32` | `Convert.ToInt32(DataCommandErrorCode.Connection)` | `1000` | Expression | Converts `DataCommandErrorCode.Connection` to `1000`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DataCommandErrorCode.Statement)` | `2000` | Expression | Converts `DataCommandErrorCode.Statement` to `2000`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DataCommandErrorCode.IncompatibleStatementType)` | `2001` | Expression | Converts `DataCommandErrorCode.IncompatibleStatementType` to `2001`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DataCommandErrorCode.MultipleStatements)` | `2002` | Expression | Converts `DataCommandErrorCode.MultipleStatements` to `2002`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DataCommandErrorCode.Runtime)` | `3000` | Expression | Converts `DataCommandErrorCode.Runtime` to `3000`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `DataCommandErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `DataCommandErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `DataCommandErrorCode`. + +### Known Limitations + +Currently when using either [OdbcConnectionDetails][] or [SqlServerConnectionDetails][], the [CommandException][] will not throw during the parsing process, and only during runtime, so the error code will be [Runtime][] instead of [Statement][]. This is due to the fact that the parsers used for those [ConnectionDetails][] do not throw and will try to execute the statements. + +## See Also + +### Related Data Types + +- [CommandException][] +- [Int32][] +- [String][] +- [ConnectionDetails][] +- [SqlServerConnectionDetails][] +- [OracleConnectionDetails][] +- [OdbcConnectionDetails][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working with Data Sources][] + +### External Documentation + +- [OracleBlockStatement][] +- [System.Enum][] + +[Connection]: {{< ref "#1000">}} +[Statement]: {{< ref "#2000">}} +[IncompatibleStatementType]: {{< ref "#2001">}} +[MultipleStatements]: {{< ref "#2002">}} +[Runtime]: {{< ref "#3000">}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Command.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Command.CommandText" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[Commands.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.CommandText" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[QueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.CommandText" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[NonQueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.CommandText" >}} +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} + +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/data/iparameter.md b/content/en/docs/2024.9/Reference/data-types/data/iparameter.md new file mode 100644 index 000000000..7f2caae3f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/iparameter.md @@ -0,0 +1,88 @@ +--- +title: "IParameter" +linkTitle: "IParameter" +description: "Any data type representing a parameter for use in the parameters property on the DataCommand data types." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.IParameter)

+ +## Summary + +Any data type representing a parameter for use in the [Parameters property][ParametersProperty] on the [DataCommand][] data types. + +`OracleParameter` is the most common example. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `IParameter` | +| **Full Name:** | `Cortex.DataTypes.Data.IParameter` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a parameter for use in the parameters property on the DataCommand data types. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IParameter Data Types + +Any of the following data types can be used where an `IParameter` is required: + +* [OracleParameter][] + +### Create an IParameter + +For some of the ways that an `IParameter` can be created, please see each of the `IParameter` data types: + +* [OracleParameter][CreateOracleParameter] + +### Convert IParameter to Text + +For some of the ways that an `IParameter` can be converted to text, please see each of the `IParameter` data types: + +* [OracleParameter][ConvertOracleParameter] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IParameter`. +* The Literal Editor is not available for [Input][] properties where the data type is `IParameter`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IParameter`. + +### Known Limitations + +* None + +## See Also + +### Related Data Types + +* [OracleParameter][] + +### Related Concepts + +* None + +### External Documentation + +* None + +[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" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[StructureCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} +[StructureConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.ConvertToText" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[CreateOracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.Create" >}} +[ConvertOracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.Convert" >}} +[OracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/iparameters-1.md b/content/en/docs/2024.9/Reference/data-types/data/iparameters-1.md new file mode 100644 index 000000000..005b0abb5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/iparameters-1.md @@ -0,0 +1,93 @@ +--- +title: "IParameters" +linkTitle: "IParameters" +description: "Any data type representing a parameter for use in the parameters property on the DataCommand data types." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.IParameters)

+ +## Summary + +Any data type representing a parameter for use in the [Parameters property][ParametersProperty] on the [DataCommand][] data types. + +`T` indicates the type of [IParameter][] that will be used for the advanced property. + +`OracleParameters` is the most common example. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `IParameters` | +| **Full Name:** | `Cortex.DataTypes.Data.IParameters` | +| **Alias:** | N/A | +| **Description:** | Any data type representing a parameter for use in the Parameters property on the DataCommand data types. | +| **Size:** | Varies | +| **Default Value:** | `null` | +| **Can be used as:** | `OracleParameters`, `Object`, `dynamic` | +| | `OracleParameters` (e.g. where `IParameters` is `IParameters`) | +| **Can be cast to:** | N/A | + +## Remarks + +### Most Common IParameters<T> Data Types + +Any of the following data types can be used where an `IParameters` is required: + +* [OracleParameters][] + +### Create an IParameters<T> + +For some of the ways that an `IParameters` can be created, please see each of the `IParameters` data types: + +* [OracleParameters][CreateOracleParameters] + +### Convert IParameters<T> to Text + +For some of the ways that an `IParameters` can be converted to text, please see each of the `IParameters` data types: + +* [OracleParameters][ConvertOracleParameters] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IParameters`. +* The Literal Editor is not available for [Input][] properties where the data type is `IParameters`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IParameters`. + +### Known Limitations + +* None + +## See Also + +### Related Data Types + +* [IParameter][] +* [OracleParameters][] + +### Related Concepts + +* None + +### External Documentation + +* None + +[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" >}} + +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[StructureCreateNew]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.CreateNew" >}} +[StructureConvertToText]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.ConvertToText" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[OracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[CreateOracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.Create" >}} +[ConvertOracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.Convert" >}} +[IParameter]: {{< url path="Cortex.Reference.DataTypes.Data.IParameter.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/nonquerycommand.md b/content/en/docs/2024.9/Reference/data-types/data/nonquerycommand.md new file mode 100644 index 000000000..388c39ba9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/nonquerycommand.md @@ -0,0 +1,152 @@ +--- +title: "NonQueryCommand" +linkTitle: "NonQueryCommand" +description: "Holds the information for running a Non Query command against a data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.NonQueryCommand)

+ +## Summary + +A `NonQueryCommand` data type is used to define single or multiple [Non Query Statements][Non Query Statement] that can be run against a data source. Statements can be [parameterised][Parameterised Commands], which is recommended to prevent [SQL Injection][]. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `NonQueryCommand` | +| **Full Name:** | `Cortex.DataTypes.Data.NonQueryCommand` | +| **Alias:** | N/A | +| **Description:** | Defines single or multiple Non Query Statements that can be run against a data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `DataCommand`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Command Text + +The Command Text is used to define single or multiple [Non Query Statements][Non Query Statement] that will be run against the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Parameters + +Parameters are used to pass information to the [Non Query Statements][Non Query Statement] that will be run against the data source. + +It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +For more information see [Parameterised Commands][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `true` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +## Remarks + +### Create a NonQueryCommand + +The following table shows some of the ways that a `NonQueryCommand` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `NonQueryCommand` constructor | `new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", null)` | `{CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null}` | Expression | | +| | `new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", new { InsertParameter1 = "Value1", InsertParameter2 = "Value2" })` | `{"CommandText": "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", "Parameters": { "InsertParameter1": \"Value1\", "InsertParameter2": \"Value2\" } }` | Expression | It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] | + +A `NonQueryCommand` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `CommandText`| `EncryptableText`| `$@"INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)"` | The command that will be executed against the data source. | +| `Parameters`| `dynamic`| `new { InsertParameter1 = "Value1", InsertParameter2 = "Value2" })` | The parameters that are used within a [Parameterised Command][Parameterised Commands]. | + +### Convert NonQueryCommand to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)NonQueryCommand.ToString()` | `"Cortex.DataTypes.Data.NonQueryCommand"` | Expression | ToString will return the Full Name of the NonQueryCommand Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null}` | `"Cortex.DataTypes.Data.NonQueryCommand"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null}` | `"{\r\n \"CommandText\": \"INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\\\"Value1\\\", \\\"Value2\\\")\",\r\n \"Parameters\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +The `@` symbol denotes a parameter within the [CommandText][] (e.g. `"INSERT INTO Table (FirstColumn) VALUES (@Parameter)"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +For more information see [Parameterised Commands][Block: Parameterised Commands]. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `NonQueryCommand`. +* The Literal Editor is available for [Input][] properties where the data type is `NonQueryCommand`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `NonQueryCommand`, then its Full Name will be returned; instead of a representation of the data within the `NonQueryCommand`. + +In future this limitation may be removed. + +#### Multiple SQL Commands (Oracle Only) + +For Oracle you must use [block statement syntax][OracleBlockStatement] to execute multiple commands, otherwise a [CommandException][CommandExceptionRuntime] will be thrown. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Command][] +* [Commands][] +* [QueryCommand][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [OracleBlockStatement][] +* [SQL Injection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Non Query Statement]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.NonQueryStatements" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[CommandExceptionRuntime]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.Runtime" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} +[SQL Injection]: {{< url path="W3.SqlInjection" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/data/odbcconnectiondetails.md b/content/en/docs/2024.9/Reference/data-types/data/odbcconnectiondetails.md new file mode 100644 index 000000000..44036a187 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/odbcconnectiondetails.md @@ -0,0 +1,102 @@ +--- +title: "OdbcConnectionDetails" +linkTitle: "OdbcConnectionDetails" +description: "The data type representing configuration for establishing and maintaining a connection to an ODBC data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.OdbcConnectionDetails)

+ +## Summary + +The `OdbcConnectionDetails` data type is used to establish and maintain a connection to an ODBC data source. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `OdbcConnectionDetails` | +| **Full Name:** | `Cortex.DataTypes.Data.OdbcConnectionDetails` | +| **Alias:** | N/A | +| **Description:** | The data type representing configuration for establishing and maintaining a connection to an ODBC data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `ConnectionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Connection String + +The Connection String that is used to connect to an ODBC data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@"Dsn=DSN Name;Driver=Driver Name;"` | + +## Remarks + +### Create an OdbcConnectionDetails + +The following table shows some of the ways that a `OdbcConnectionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `OdbcConnectionDetails` constructor | `new OdbcConnectionDetails("DSN=LocalHost;Driver={ODBC Driver Version}")` | `{"ConnectionString": "DSN=LocalHost;Driver={ODBC Driver Version}"}` | Expression | | + +A `OdbcConnectionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Connection String`| `EncryptableText`| `$@"DSN=LocalHost;Driver={ODBC Driver Version}"` | The Connection String that is used to connect to an ODBC data source. | + +### Connection Strings + +A [Connection String][] must be provided in order to connect to an ODBC data source. The [Connection String][] can be formatted differently depending on the ODBC driver. See [ConnectionStrings.com][] for a list of ODBC connection strings under each specific data source. + +Please see [Working with Data Sources][] for a list of other supported data sources (e.g. SQL Server) and how to construct valid connection strings for them. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `OdbcConnectionDetails`. +* The Literal Editor is not available for [Input][] properties where the data type is `OdbcConnectionDetails`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `OdbcConnectionDetails`. + +### Known limitations + +* Currently string values cannot be used as a parameter when connected to an Microsoft Access data source. + +## See Also + +### Related Data Types + +* [ConnectionDetails][] +* [OracleConnectionDetails][] +* [SqlServerConnectionDetails][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [ConnectionStrings.com][] + +[Connection String]: {{< ref "#connection-string" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[ConnectionStrings.com]: {{< url path="ConnectionStrings.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/oracleconnectiondetails.md b/content/en/docs/2024.9/Reference/data-types/data/oracleconnectiondetails.md new file mode 100644 index 000000000..6712f85f8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/oracleconnectiondetails.md @@ -0,0 +1,114 @@ +--- +title: "OracleConnectionDetails" +linkTitle: "OracleConnectionDetails" +description: "The data type representing configuration for establishing and maintaining a connection to an Oracle data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.OracleConnectionDetails)

+ +## Summary + +The `OracleConnectionDetails` data type is used to establish and maintain a connection to an Oracle data source. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `OracleConnectionDetails` | +| **Full Name:** | `Cortex.DataTypes.Data.OracleConnectionDetails` | +| **Alias:** | N/A | +| **Description:** | The data type representing configuration for establishing and maintaining a connection to an Oracle data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `ConnectionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Connection String + +The Connection String that is used to connect to an Oracle data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@"Data Source=Connection String;"` | + +## Remarks + +### Create an OracleConnectionDetails + +The following table shows some of the ways that an `OracleConnectionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `OracleConnectionDetails` constructor | `new OracleConnectionDetails("Data Source=Connection String;")` | `{connectionString: $@"Data Source=Connection String;"}` | Expression | | + +An `OracleConnectionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Connection String`| `EncryptableText`| `$@"Data Source=Connection String;"` | The Connection String that is used to connect to an Oracle database. | + +### Connection Strings + +A [Connection String][] must be provided in order to connect to an Oracle data source. The [Connection String][] can be formatted differently depending on the way the connection will be created and maintained (e.g. Windows user authentication vs TNS). See [ConnectionStrings.com][] for a list of Oracle connection strings. + +Please see [Working with Data Sources][] for a list of other supported data sources (e.g. SQL Server) and how to construct valid connection strings for them. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `OracleConnectionDetails`. +* The Literal Editor is not available for [Input][] properties where the data type is `OracleConnectionDetails`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `OracleConnectionDetails`. + +### Known limitations + +* When using the [OracleConnectionDetails][] to execute multiple commands in the [Command Property][CommandProperty] (using the [QueryCommand][] or [NonQueryCommand][] datatype), as Oracle uses PL/SQL, you must use the block statement syntax. See [OracleBlockStatement][] for more. + +* The [Integrated Security][OracleIntegratedSecurityConnectionString] connection string format is not supported. + +## See Also + +### Related Data Types + +* [ConnectionDetails][] +* [OdbcConnectionDetails][] +* [SqlServerConnectionDetails][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [ConnectionStrings.com][] +* [OracleBlockStatement][] + +[Connection String]: {{< ref "#connection-string" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} +[SqlServerConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.SqlServerConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[QueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.CommandText" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[NonQueryCommand.CommandText]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.CommandText" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[ConnectionStrings.com]: {{< url path="ConnectionStrings.OracleConnection" >}} +[OracleIntegratedSecurityConnectionString]: {{< url path="ConnectionStrings.OracleConnectionIntegratedSecurity" >}} +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/oraclemappingtype.md b/content/en/docs/2024.9/Reference/data-types/data/oraclemappingtype.md new file mode 100644 index 000000000..09adc6194 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/oraclemappingtype.md @@ -0,0 +1,619 @@ +--- +title: "OracleMappingType" +linkTitle: "OracleMappingType" +description: "Used to represent the Oracle type used for the Parameter." +--- + +# {{% param title %}} + +

(Dapper.Oracle.OracleMappingType)

+ +## Summary + +The `OracleMappingType` data type is used to represent the Oracle type of the [OracleParameter][]. + +`OracleMappingType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------------------------------| +| **Category:** | Data | +| **Name:** | `OracleMappingType` | +| **Full Name:** | `Dapper.Oracle.OracleMappingType` | +| **Alias:** | N/A | +| **Description:** | Used to represent the Oracle type of the [OracleParameter][]. | +| **Default Value:** | `OracleMappingType.BFile` | +| **Can be used as:** | `OracleMappingType`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)OracleMappingType.BFile` or `(System.Int16)OracleMappingType.BFile` or `(short)OracleMappingType.BFile`) | +| | `Int32` (e.g. `(Int32)OracleMappingType.BFile` or `(System.Int32)OracleMappingType.BFile` or `(int)OracleMappingType.BFile`) | +| | `Int64` (e.g. `(Int64)OracleMappingType.BFile` or `(System.Int64)OracleMappingType.BFile` or `(long)OracleMappingType.BFile`) | +| | `Single` (e.g. `(Single)OracleMappingType.BFile` or `(System.Single)OracleMappingType.BFile` or `(float)OracleMappingType.BFile`) | +| | `Double` (e.g. `(Double)OracleMappingType.BFile` or `(System.Double)OracleMappingType.BFile` or `(double)OracleMappingType.BFile`) | + +## Values + +### BFile + +| | | +|------------|----------------------------| +| **Name:** | BFile | +| **Value:** | [Int32][] with value `101` | +| **Notes:** | | + +### Blob + +| | | +|------------|----------------------------| +| **Name:** | Blob | +| **Value:** | [Int32][] with value `102` | +| **Notes:** | | + +### Byte + +| | | +|------------|----------------------------| +| **Name:** | Byte | +| **Value:** | [Int32][] with value `103` | +| **Notes:** | | + +### Char + +| | | +|------------|----------------------------| +| **Name:** | Char | +| **Value:** | [Int32][] with value `104` | +| **Notes:** | | + +### Clob + +| | | +|------------|----------------------------| +| **Name:** | Clob | +| **Value:** | [Int32][] with value `105` | +| **Notes:** | | + +### Date + +| | | +|------------|----------------------------| +| **Name:** | Date | +| **Value:** | [Int32][] with value `106` | +| **Notes:** | | + +### Decimal + +| | | +|------------|----------------------------| +| **Name:** | Decimal | +| **Value:** | [Int32][] with value `107` | +| **Notes:** | | + +### Double + +| | | +|------------|----------------------------| +| **Name:** | Double | +| **Value:** | [Int32][] with value `108` | +| **Notes:** | | + +### Long + +| | | +|------------|----------------------------| +| **Name:** | Long | +| **Value:** | [Int32][] with value `109` | +| **Notes:** | | + +### LongRaw + +| | | +|------------|----------------------------| +| **Name:** | LongRaw | +| **Value:** | [Int32][] with value `110` | +| **Notes:** | | + +### Int16 + +| | | +|------------|----------------------------| +| **Name:** | Int16 | +| **Value:** | [Int32][] with value `111` | +| **Notes:** | | + +### Int32 + +| | | +|------------|----------------------------| +| **Name:** | Int32 | +| **Value:** | [Int32][] with value `112` | +| **Notes:** | | + +### Int64 + +| | | +|------------|----------------------------| +| **Name:** | Int64 | +| **Value:** | [Int32][] with value `113` | +| **Notes:** | | + +### IntervalDS + +| | | +|------------|----------------------------| +| **Name:** | IntervalDS | +| **Value:** | [Int32][] with value `114` | +| **Notes:** | | + +### IntervalYM + +| | | +|------------|----------------------------| +| **Name:** | IntervalYM | +| **Value:** | [Int32][] with value `115` | +| **Notes:** | | + +### NClob + +| | | +|------------|----------------------------| +| **Name:** | NClob | +| **Value:** | [Int32][] with value `116` | +| **Notes:** | | + +### NChar + +| | | +|------------|----------------------------| +| **Name:** | NChar | +| **Value:** | [Int32][] with value `117` | +| **Notes:** | | + +### NVarchar2 + +| | | +|------------|----------------------------| +| **Name:** | NVarchar2 | +| **Value:** | [Int32][] with value `119` | +| **Notes:** | | + +### Raw + +| | | +|------------|----------------------------| +| **Name:** | Raw | +| **Value:** | [Int32][] with value `120` | +| **Notes:** | | + +### RefCursor + +| | | +|------------|----------------------------| +| **Name:** | RefCursor | +| **Value:** | [Int32][] with value `121` | +| **Notes:** | | + +### Single + +| | | +|------------|----------------------------| +| **Name:** | Single | +| **Value:** | [Int32][] with value `122` | +| **Notes:** | | + +### TimeStamp + +| | | +|------------|----------------------------| +| **Name:** | TimeStamp | +| **Value:** | [Int32][] with value `123` | +| **Notes:** | | + +### TimeStampLTZ + +| | | +|------------|----------------------------| +| **Name:** | TimeStampLTZ | +| **Value:** | [Int32][] with value `124` | +| **Notes:** | | + +### TimeStampTZ + +| | | +|------------|----------------------------| +| **Name:** | TimeStampLZ | +| **Value:** | [Int32][] with value `125` | +| **Notes:** | | + +### Varchar2 + +| | | +|------------|----------------------------| +| **Name:** | Varchar2 | +| **Value:** | [Int32][] with value `126` | +| **Notes:** | | + +### XmlType + +| | | +|------------|----------------------------| +| **Name:** | XmlType | +| **Value:** | [Int32][] with value `127` | +| **Notes:** | | + +### BinaryDouble + +| | | +|------------|----------------------------| +| **Name:** | BinaryDouble | +| **Value:** | [Int32][] with value `132` | +| **Notes:** | | + +### BinaryFloat + +| | | +|------------|----------------------------| +| **Name:** | BinaryFloat | +| **Value:** | [Int32][] with value `133` | +| **Notes:** | | + +## Remarks + +### Create OracleMappingType + +The following table shows some of the ways that `OracleMappingType` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `OracleMappingType` expression | `OracleMappingType.BFile` | `OracleMappingType.BFile`| Expression | | +| | `OracleMappingType.Blob` | `OracleMappingType.Blob`| Expression | | +| | `OracleMappingType.Byte` | `OracleMappingType.Byte`| Expression | | +| | `OracleMappingType.Char` | `OracleMappingType.Char`| Expression | | +| | `OracleMappingType.Clob` | `OracleMappingType.Clob` | Expression | | +| | `OracleMappingType.Date` | `OracleMappingType.Date` | Expression | | +| | `OracleMappingType.Decimal` | `OracleMappingType.Decimal` | Expression | | +| | `OracleMappingType.Double` | `OracleMappingType.Double` | Expression | | +| | `OracleMappingType.Long` | `OracleMappingType.Long` | Expression | | +| | `OracleMappingType.LongRaw` | `OracleMappingType.LongRaw` | Expression | | +| | `OracleMappingType.Int16` | `OracleMappingType.Int16` | Expression | | +| | `OracleMappingType.Int32` | `OracleMappingType.Int32` | Expression | | +| | `OracleMappingType.Int64` | `OracleMappingType.Int64` | Expression | | +| | `OracleMappingType.IntervalDS` | `OracleMappingType.IntervalDS` | Expression | | +| | `OracleMappingType.IntervalYM` | `OracleMappingType.IntervalYM` | Expression | | +| | `OracleMappingType.NClob` | `OracleMappingType.NClob` | Expression | | +| | `OracleMappingType.NChar` | `OracleMappingType.NChar` | Expression | | +| | `OracleMappingType.NVarchar2` | `OracleMappingType.NVarchar2` | Expression | | +| | `OracleMappingType.Raw` | `OracleMappingType.Raw` | Expression | | +| | `OracleMappingType.RefCursor` | `OracleMappingType.RefCursor` | Expression | | +| | `OracleMappingType.Single` | `OracleMappingType.Single` | Expression | | +| | `OracleMappingType.TimeStamp` | `OracleMappingType.TimeStamp` | Expression | | +| | `OracleMappingType.TimeStampLTZ` | `OracleMappingType.TimeStampLTZ` | Expression | | +| | `OracleMappingType.TimeStampLZ` | `OracleMappingType.TimeStampLZ` | Expression | | +| | `OracleMappingType.Varchar2` | `OracleMappingType.Varchar2` | Expression | | +| | `OracleMappingType.XmlType` | `OracleMappingType.XmlType` | Expression | | +| | `OracleMappingType.BinaryDouble` | `OracleMappingType.BinaryDouble` | Expression | | +| | `OracleMappingType.BinaryFloat` | `OracleMappingType.BinaryFloat` | Expression | | +| Use [Explicit Casting][] | `(OracleMappingType)101` | `OracleMappingType.BFile`| Expression | | +| | `(OracleMappingType)102` | `OracleMappingType.Blob`| Expression | | +| | `(OracleMappingType)103` | `OracleMappingType.Byte`| Expression | | +| | `(OracleMappingType)104` | `OracleMappingType.Char`| Expression | | +| | `(OracleMappingType)105` | `OracleMappingType.Clob` | Expression | | +| | `(OracleMappingType)106` | `OracleMappingType.Date` | Expression | | +| | `(OracleMappingType)107` | `OracleMappingType.Decimal` | Expression | | +| | `(OracleMappingType)108` | `OracleMappingType.Double` | Expression | | +| | `(OracleMappingType)109` | `OracleMappingType.Long` | Expression | | +| | `(OracleMappingType)110` | `OracleMappingType.LongRaw` | Expression | | +| | `(OracleMappingType)111` | `OracleMappingType.Int16` | Expression | | +| | `(OracleMappingType)112` | `OracleMappingType.Int32` | Expression | | +| | `(OracleMappingType)113` | `OracleMappingType.Int64` | Expression | | +| | `(OracleMappingType)114` | `OracleMappingType.IntervalDS` | Expression | | +| | `(OracleMappingType)115` | `OracleMappingType.IntervalYM` | Expression | | +| | `(OracleMappingType)116` | `OracleMappingType.NClob` | Expression | | +| | `(OracleMappingType)117` | `OracleMappingType.NChar` | Expression | | +| | `(OracleMappingType)119` | `OracleMappingType.NVarchar2` | Expression | | +| | `(OracleMappingType)120` | `OracleMappingType.Raw` | Expression | | +| | `(OracleMappingType)121` | `OracleMappingType.RefCursor` | Expression | | +| | `(OracleMappingType)122` | `OracleMappingType.Single` | Expression | | +| | `(OracleMappingType)123` | `OracleMappingType.TimeStamp` | Expression | | +| | `(OracleMappingType)124` | `OracleMappingType.TimeStampLTZ` | Expression | | +| | `(OracleMappingType)125` | `OracleMappingType.TimeStampLZ` | Expression | | +| | `(OracleMappingType)126` | `OracleMappingType.Varchar2` | Expression | | +| | `(OracleMappingType)127` | `OracleMappingType.XmlType` | Expression | | +| | `(OracleMappingType)132` | `OracleMappingType.BinaryDouble` | Expression | | +| | `(OracleMappingType)133` | `OracleMappingType.BinaryFloat` | Expression | | +| Use `Enum.Parse` | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "BFile")` | `OracleMappingType.BFile`| Expression | Parses `"BFile"` and converts it to `OracleMappingType.BFile`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Blob")` | `OracleMappingType.Blob`| Expression | Parses `"Blob"` and converts it to `OracleMappingType.Blob`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Byte")` | `OracleMappingType.Byte`| Expression | Parses `"Byte"` and converts it to `OracleMappingType.Byte`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Char")` | `OracleMappingType.Char`| Expression | Parses `"Char"` and converts it to `OracleMappingType.Char`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Clob")` | `OracleMappingType.Clob`| Expression | Parses `"Clob"` and converts it to `OracleMappingType.Clob`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Date")` | `OracleMappingType.Date`| Expression | Parses `"Date"` and converts it to `OracleMappingType.Date`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Decimal")` | `OracleMappingType.Decimal`| Expression | Parses `"Decimal"` and converts it to `OracleMappingType.Decimal`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Double")` | `OracleMappingType.Double`| Expression | Parses `"Double"` and converts it to `OracleMappingType.Double`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Long")` | `OracleMappingType.Long`| Expression | Parses `"Long"` and converts it to `OracleMappingType.Long`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "LongRaw")` | `OracleMappingType.LongRaw`| Expression | Parses `"LongRaw"` and converts it to `OracleMappingType.LongRaw`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Int16")` | `OracleMappingType.Int16`| Expression | Parses `"Int16"` and converts it to `OracleMappingType.Int16`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Int32")` | `OracleMappingType.Int32`| Expression | Parses `"Int32"` and converts it to `OracleMappingType.Int32`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Int64")` | `OracleMappingType.Int64`| Expression | Parses `"Int64"` and converts it to `OracleMappingType.Int64`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "IntervalDS")` | `OracleMappingType.IntervalDS`| Expression | Parses `"IntervalDS"` and converts it to `OracleMappingType.IntervalDS`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "IntervalYM")` | `OracleMappingType.IntervalYM`| Expression | Parses `"IntervalYM"` and converts it to `OracleMappingType.IntervalYM`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "NClob")` | `OracleMappingType.NClob`| Expression | Parses `"NClob"` and converts it to `OracleMappingType.NClob`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "NChar")` | `OracleMappingType.NChar`| Expression | Parses `"NChar"` and converts it to `OracleMappingType.NChar`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "NVarchar2")` | `OracleMappingType.NVarchar2`| Expression | Parses `"NVarchar2"` and converts it to `OracleMappingType.NVarchar2`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Raw")` | `OracleMappingType.Raw`| Expression | Parses `"Raw"` and converts it to `OracleMappingType.Raw`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "RefCursor")` | `OracleMappingType.RefCursor`| Expression | Parses `"RefCursor"` and converts it to `OracleMappingType.RefCursor`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Single")` | `OracleMappingType.Single`| Expression | Parses `"Single"` and converts it to `OracleMappingType.Single`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "TimeStamp")` | `OracleMappingType.TimeStamp`| Expression | Parses `"TimeStamp"` and converts it to `OracleMappingType.TimeStamp`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "TimeStampLTZ")` | `OracleMappingType.TimeStampLTZ`| Expression | Parses `"TimeStampLTZ"` and converts it to `OracleMappingType.TimeStampLTZ`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "TimeStampLZ")` | `OracleMappingType.TimeStampLZ`| Expression | Parses `"TimeStampLZ"` and converts it to `OracleMappingType.TimeStampLZ`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "Varchar2")` | `OracleMappingType.Varchar2`| Expression | Parses `"Varchar2"` and converts it to `OracleMappingType.Varchar2`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "XmlType")` | `OracleMappingType.XmlType`| Expression | Parses `"XmlType"` and converts it to `OracleMappingType.XmlType`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "BinaryDouble")` | `OracleMappingType.BinaryDouble`| Expression | Parses `"BinaryDouble"` and converts it to `OracleMappingType.BinaryDouble`. See [Enum.Parse][] | +| | `(OracleMappingType)Enum.Parse(typeof(OracleMappingType), "BinaryFloat")` | `OracleMappingType.BinaryFloat`| Expression | Parses `"BinaryFloat"` and converts it to `OracleMappingType.BinaryFloat`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 101)` | `OracleMappingType.BFile`| Expression | Converts `101` to `OracleMappingType.BFile` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 102)` | `OracleMappingType.Blob`| Expression | Converts `102` to `OracleMappingType.Blob` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 103)` | `OracleMappingType.Byte`| Expression | Converts `103` to `OracleMappingType.Byte` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 104)` | `OracleMappingType.Char`| Expression | Converts `104` to `OracleMappingType.Char` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 105)` | `OracleMappingType.Clob` | Expression | Converts `105` to `OracleMappingType.Clob` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 106)` | `OracleMappingType.Date` | Expression | Converts `106` to `OracleMappingType.Date` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 107)` | `OracleMappingType.Decimal` | Expression | Converts `107` to `OracleMappingType.Decimal` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 108)` | `OracleMappingType.Double` | Expression | Converts `108` to `OracleMappingType.Double` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 109)` | `OracleMappingType.Long` | Expression | Converts `109` to `OracleMappingType.Long` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 110)` | `OracleMappingType.LongRaw` | Expression | Converts `110` to `OracleMappingType.LongRaw` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 111)` | `OracleMappingType.Int16` | Expression | Converts `111` to `OracleMappingType.Int16` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 112)` | `OracleMappingType.Int32` | Expression | Converts `112` to `OracleMappingType.Int32` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 113)` | `OracleMappingType.Int64` | Expression | Converts `113` to `OracleMappingType.Int64` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 114)` | `OracleMappingType.IntervalDS` | Expression | Converts `114` to `OracleMappingType.IntervalDS` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 115)` | `OracleMappingType.IntervalYM` | Expression | Converts `115` to `OracleMappingType.IntervalYM` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 116)` | `OracleMappingType.NClob` | Expression | Converts `116` to `OracleMappingType.NClob` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 117)` | `OracleMappingType.NChar` | Expression | Converts `117` to `OracleMappingType.NChar` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 119)` | `OracleMappingType.NVarchar2` | Expression | Converts `119` to `OracleMappingType.NVarchar2` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 120)` | `OracleMappingType.Raw` | Expression | Converts `120` to `OracleMappingType.Raw` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 121)` | `OracleMappingType.RefCursor` | Expression | Converts `121` to `OracleMappingType.RefCursor` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 122)` | `OracleMappingType.Single` | Expression | Converts `122` to `OracleMappingType.Single` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 123)` | `OracleMappingType.TimeStamp` | Expression | Converts `123` to `OracleMappingType.TimeStamp` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 124)` | `OracleMappingType.TimeStampLTZ` | Expression | Converts `124` to `OracleMappingType.TimeStampLTZ` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 125)` | `OracleMappingType.TimeStampLZ` | Expression | Converts `125` to `OracleMappingType.TimeStampLZ` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 126)` | `OracleMappingType.Varchar2` | Expression | Converts `126` to `OracleMappingType.Varchar2` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 127)` | `OracleMappingType.XmlType` | Expression | Converts `127` to `OracleMappingType.XmlType` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 132)` | `OracleMappingType.BinaryDouble` | Expression | Converts `132` to `OracleMappingType.BinaryDouble` value. See [Enum.ToObject][] | +| | `(OracleMappingType)Enum.ToObject(typeof(OracleMappingType), 133)` | `OracleMappingType.BinaryFloat` | Expression | Converts `133` to `OracleMappingType.BinaryFloat` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert OracleMappingType to Text + +The following table shows some of the ways that a `OracleMappingType` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `OracleMappingType.BFile.ToString()` | `"BFile"` | Expression | Converts `OracleMappingType.BFile` to `"BFile"`. See [Enum.ToString][] | +| | `OracleMappingType.Byte.ToString()` | `"Blob"` | Expression | Converts `OracleMappingType.Blob` to `"Blob"`. See [Enum.ToString][] | +| | `OracleMappingType.Byte.ToString()` | `"Byte"` | Expression | Converts `OracleMappingType.Byte` to `"Byte"`. See [Enum.ToString][] | +| | `OracleMappingType.Char.ToString()` | `"Char"` | Expression | Converts `OracleMappingType.Char` to `"Char"`. See [Enum.ToString][] | +| | `OracleMappingType.Clob.ToString()` | `"Clob"` | Expression | Converts `OracleMappingType.Clob` to `"Clob"`. See [Enum.ToString][] | +| | `OracleMappingType.Date.ToString()` | `"Date"` | Expression | Converts `OracleMappingType.Date` to `"Date"`. See [Enum.ToString][] | +| | `OracleMappingType.Decimal.ToString()` | `"Decimal"` | Expression | Converts `OracleMappingType.Decimal` to `"Decimal"`. See [Enum.ToString][] | +| | `OracleMappingType.Double.ToString()` | `"Double"` | Expression | Converts `OracleMappingType.Double` to `"Double"`. See [Enum.ToString][] | +| | `OracleMappingType.Long.ToString()` | `"Long"` | Expression | Converts `OracleMappingType.Long` to `"Long"`. See [Enum.ToString][] | +| | `OracleMappingType.LongRaw.ToString()` | `"LongRaw"` | Expression | Converts `OracleMappingType.LongRaw` to `"LongRaw"`. See [Enum.ToString][] | +| | `OracleMappingType.Int16.ToString()` | `"Int16"` | Expression | Converts `OracleMappingType.Int16` to `"Int16"`. See [Enum.ToString][] | +| | `OracleMappingType.Int32.ToString()` | `"Int32"` | Expression | Converts `OracleMappingType.Int32` to `"Int32"`. See [Enum.ToString][] | +| | `OracleMappingType.Int64.ToString()` | `"Int64"` | Expression | Converts `OracleMappingType.Int64` to `"Int64"`. See [Enum.ToString][] | +| | `OracleMappingType.IntervalDS.ToString()` | `"IntervalDS"` | Expression | Converts `OracleMappingType.IntervalDS` to `"IntervalDS"`. See [Enum.ToString][] | +| | `OracleMappingType.IntervalYM.ToString()` | `"IntervalYM"` | Expression | Converts `OracleMappingType.IntervalYM` to `"IntervalYM"`. See [Enum.ToString][] | +| | `OracleMappingType.NClob.ToString()` | `"NClob"` | Expression | Converts `OracleMappingType.NClob` to `"NClob"`. See [Enum.ToString][] | +| | `OracleMappingType.NChar.ToString()` | `"NChar"` | Expression | Converts `OracleMappingType.NChar` to `"NChar"`. See [Enum.ToString][] | +| | `OracleMappingType.NVarchar2.ToString()` | `"NVarchar2"` | Expression | Converts `OracleMappingType.NVarchar2` to `"NVarchar2"`. See [Enum.ToString][] | +| | `OracleMappingType.Raw.ToString()` | `"Raw"` | Expression | Converts `OracleMappingType.Raw` to `"Raw"`. See [Enum.ToString][] | +| | `OracleMappingType.RefCursor.ToString()` | `"RefCursor"` | Expression | Converts `OracleMappingType.RefCursor` to `"RefCursor"`. See [Enum.ToString][] | +| | `OracleMappingType.Single.ToString()` | `"Single"` | Expression | Converts `OracleMappingType.Single` to `"Single"`. See [Enum.ToString][] | +| | `OracleMappingType.TimeStamp.ToString()` | `"TimeStamp"` | Expression | Converts `OracleMappingType.TimeStamp` to `"TimeStamp"`. See [Enum.ToString][] | +| | `OracleMappingType.TimeStampLTZ.ToString()` | `"TimeStampLTZ"` | Expression | Converts `OracleMappingType.TimeStampLTZ` to `"TimeStampLTZ"`. See [Enum.ToString][] | +| | `OracleMappingType.TimeStampLZ.ToString()` | `"TimeStampLZ"` | Expression | Converts `OracleMappingType.TimeStampLZ` to `"TimeStampLZ"`. See [Enum.ToString][] | +| | `OracleMappingType.Varchar2.ToString()` | `"Varchar2"` | Expression | Converts `OracleMappingType.Varchar2` to `"Varchar2"`. See [Enum.ToString][] | +| | `OracleMappingType.XmlType.ToString()` | `"XmlType"` | Expression | Converts `OracleMappingType.XmlType` to `"XmlType"`. See [Enum.ToString][] | +| | `OracleMappingType.BinaryDouble.ToString()` | `"BinaryDouble"` | Expression | Converts `OracleMappingType.BinaryDouble` to `"BinaryDouble"`. See [Enum.ToString][] | +| | `OracleMappingType.BinaryFloat.ToString()` | `"BinaryFloat"` | Expression | Converts `OracleMappingType.BinaryFloat` to `"BinaryFloat"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(OracleMappingType.BFile)` | `"BFile"` | Expression | Converts `OracleMappingType.BFile` to `"BFile"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Byte)` | `"Byte"` | Expression | Converts `OracleMappingType.Byte` to `"Byte"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Char)` | `"Char"` | Expression | Converts `OracleMappingType.Char` to `"Char"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Clob)` | `"Clob"` | Expression | Converts `OracleMappingType.Clob` to `"Clob"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Date)` | `"Date"` | Expression | Converts `OracleMappingType.Date` to `"Date"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Decimal)` | `"Decimal"` | Expression | Converts `OracleMappingType.Decimal` to `"Decimal"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Double)` | `"Double"` | Expression | Converts `OracleMappingType.Double` to `"Double"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Long)` | `"Long"` | Expression | Converts `OracleMappingType.Long` to `"Long"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.LongRaw)` | `"LongRaw"` | Expression | Converts `OracleMappingType.LongRaw` to `"LongRaw"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Int16)` | `"Int16"` | Expression | Converts `OracleMappingType.Int16` to `"Int16"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Int32)` | `"Int32"` | Expression | Converts `OracleMappingType.Int32` to `"Int32"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Int64)` | `"Int64"` | Expression | Converts `OracleMappingType.Int64` to `"Int64"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.IntervalDS)` | `"IntervalDS"` | Expression | Converts `OracleMappingType.IntervalDS` to `"IntervalDS"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.IntervalYM)` | `"IntervalYM"` | Expression | Converts `OracleMappingType.IntervalYM` to `"IntervalYM"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.NClob)` | `"NClob"` | Expression | Converts `OracleMappingType.NClob` to `"NClob"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.NChar)` | `"NChar"` | Expression | Converts `OracleMappingType.NChar` to `"NChar"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.NVarchar2)` | `"NVarchar2"` | Expression | Converts `OracleMappingType.NVarchar2` to `"NVarchar2"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Raw)` | `"Raw"` | Expression | Converts `OracleMappingType.Raw` to `"Raw"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.RefCursor)` | `"RefCursor"` | Expression | Converts `OracleMappingType.RefCursor` to `"RefCursor"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Single)` | `"Single"` | Expression | Converts `OracleMappingType.Single` to `"Single"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.TimeStamp)` | `"TimeStamp"` | Expression | Converts `OracleMappingType.TimeStamp` to `"TimeStamp"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.TimeStampLTZ)` | `"TimeStampLTZ"` | Expression | Converts `OracleMappingType.TimeStampLTZ` to `"TimeStampLTZ"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.TimeStampLZ)` | `"TimeStampLZ"` | Expression | Converts `OracleMappingType.TimeStampLZ` to `"TimeStampLZ"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.Varchar2)` | `"Varchar2"` | Expression | Converts `OracleMappingType.Varchar2` to `"Varchar2"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.XmlType)` | `"XmlType"` | Expression | Converts `OracleMappingType.XmlType` to `"XmlType"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.BinaryDouble)` | `"BinaryDouble"` | Expression | Converts `OracleMappingType.BinaryDouble` to `"BinaryDouble"`. See [Convert.ToString][] | +| | `Convert.ToString(OracleMappingType.BinaryFloat)` | `"BinaryFloat"` | Expression | Converts `OracleMappingType.BinaryFloat` to `"BinaryFloat"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `OracleMappingType.BFile` | `"BFile"` | N/A | Converts `OracleMappingType.BFile` to `"BFile"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Byte` | `"Byte"` | N/A | Converts `OracleMappingType.Byte` to `"Byte"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Char` | `"Char"` | N/A | Converts `OracleMappingType.Char` to `"Char"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Clob` | `"Clob"` | N/A | Converts `OracleMappingType.Clob` to `"Clob"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Date` | `"Date"` | N/A | Converts `OracleMappingType.Date` to `"Date"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Decimal` | `"Decimal"` | N/A | Converts `OracleMappingType.Decimal` to `"Decimal"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Double` | `"Double"` | N/A | Converts `OracleMappingType.Double` to `"Double"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Long` | `"Long"` | N/A | Converts `OracleMappingType.Long` to `"Long"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.LongRaw` | `"LongRaw"` | N/A | Converts `OracleMappingType.LongRaw` to `"LongRaw"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Int16` | `"Int16"` | N/A | Converts `OracleMappingType.Int16` to `"Int16"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Int32` | `"Int32"` | N/A | Converts `OracleMappingType.Int32` to `"Int32"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Int64` | `"Int64"` | N/A | Converts `OracleMappingType.Int64` to `"Int64"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.IntervalDS` | `"IntervalDS"` | N/A | Converts `OracleMappingType.IntervalDS` to `"IntervalDS"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.IntervalYM` | `"IntervalYM"` | N/A | Converts `OracleMappingType.IntervalYM` to `"IntervalYM"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.NClob` | `"NClob"` | N/A | Converts `OracleMappingType.NClob` to `"NClob"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.NChar` | `"NChar"` | N/A | Converts `OracleMappingType.NChar` to `"NChar"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.NVarchar2` | `"NVarchar2"` | N/A | Converts `OracleMappingType.NVarchar2` to `"NVarchar2"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Raw` | `"Raw"` | N/A | Converts `OracleMappingType.Raw` to `"Raw"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.RefCursor` | `"RefCursor"` | N/A | Converts `OracleMappingType.RefCursor` to `"RefCursor"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Single` | `"Single"` | N/A | Converts `OracleMappingType.Single` to `"Single"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.TimeStamp` | `"TimeStamp"` | N/A | Converts `OracleMappingType.TimeStamp` to `"TimeStamp"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.TimeStampLTZ` | `"TimeStampLTZ"` | N/A | Converts `OracleMappingType.TimeStampLTZ` to `"TimeStampLTZ"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.TimeStampLZ` | `"TimeStampLZ"` | N/A | Converts `OracleMappingType.TimeStampLZ` to `"TimeStampLZ"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.Varchar2` | `"Varchar2"` | N/A | Converts `OracleMappingType.Varchar2` to `"Varchar2"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.XmlType` | `"XmlType"` | N/A | Converts `OracleMappingType.XmlType` to `"XmlType"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.BinaryDouble` | `"BinaryDouble"` | N/A | Converts `OracleMappingType.BinaryDouble` to `"BinaryDouble"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `OracleMappingType.BinaryFloat` | `"BinaryFloat"` | N/A | Converts `OracleMappingType.BinaryFloat` to `"BinaryFloat"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `OracleMappingType.BFile` | `"101"` | N/A | Converts `OracleMappingType.BFile` to `"101"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Blob` | `"102"` | N/A | Converts `OracleMappingType.Blob` to `"102"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Byte` | `"103"` | N/A | Converts `OracleMappingType.Byte` to `"103"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Char` | `"104"` | N/A | Converts `OracleMappingType.Char` to `"104"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Clob` | `"105"` | N/A | Converts `OracleMappingType.Clob` to `"105"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Date` | `"106"` | N/A | Converts `OracleMappingType.Date` to `"106"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Decimal` | `"107"` | N/A | Converts `OracleMappingType.Decimal` to `"107"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Double` | `"108"` | N/A | Converts `OracleMappingType.Double` to `"108"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Long` | `"109"` | N/A | Converts `OracleMappingType.Long` to `"109"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.LongRaw` | `"110"` | N/A | Converts `OracleMappingType.LongRaw` to `"110"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Int16` | `"111"` | N/A | Converts `OracleMappingType.Int16` to `"111"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Int32` | `"112"` | N/A | Converts `OracleMappingType.Int32` to `"112"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Int64` | `"113"` | N/A | Converts `OracleMappingType.Int64` to `"113"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.IntervalDS` | `"114"` | N/A | Converts `OracleMappingType.IntervalDS` to `"114"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.IntervalYM` | `"115"` | N/A | Converts `OracleMappingType.IntervalYM` to `"115"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.NClob` | `"116"` | N/A | Converts `OracleMappingType.NClob` to `"116"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.NChar` | `"117"` | N/A | Converts `OracleMappingType.NChar` to `"117"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.NVarchar2` | `"119"` | N/A | Converts `OracleMappingType.NVarchar2` to `"119"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Raw` | `"120"` | N/A | Converts `OracleMappingType.Raw` to `"120"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.RefCursor` | `"121"` | N/A | Converts `OracleMappingType.RefCursor` to `"121"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Single` | `"122"` | N/A | Converts `OracleMappingType.Single` to `"122"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.TimeStamp` | `"123"` | N/A | Converts `OracleMappingType.TimeStamp` to `"123"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.TimeStampLTZ` | `"124"` | N/A | Converts `OracleMappingType.TimeStampLTZ` to `"124"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.TimeStampLZ` | `"125"` | N/A | Converts `OracleMappingType.TimeStampLZ` to `"125"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.Varchar2` | `"126"` | N/A | Converts `OracleMappingType.Varchar2` to `"126"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.XmlType` | `"127"` | N/A | Converts `OracleMappingType.XmlType` to `"127"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.BinaryDouble` | `"132"` | N/A | Converts `OracleMappingType.BinaryDouble` to `"132"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `OracleMappingType.BinaryFloat` | `"133"` | N/A | Converts `OracleMappingType.BinaryFloat` to `"133"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert OracleMappingType to a Number + +The following table shows some of the ways that a `OracleMappingType` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)OracleMappingType.BFile` | `101` | Expression | [Casts][Explicit Casting] `OracleMappingType.BFile` to `101` | +| | `(Int32)OracleMappingType.Blob` | `102` | Expression | [Casts][Explicit Casting] `OracleMappingType.Blob` to `102` | +| | `(Int32)OracleMappingType.Byte` | `103` | Expression | [Casts][Explicit Casting] `OracleMappingType.Byte` to `103` | +| | `(Int32)OracleMappingType.Char` | `104` | Expression | [Casts][Explicit Casting] `OracleMappingType.Char` to `104` | +| | `(Int32)OracleMappingType.Clob` | `105` | Expression | [Casts][Explicit Casting] `OracleMappingType.Clob` to `105` | +| | `(Int32)OracleMappingType.Date` | `106` | Expression | [Casts][Explicit Casting] `OracleMappingType.Date` to `106` | +| | `(Int32)OracleMappingType.Decimal` | `107` | Expression | [Casts][Explicit Casting] `OracleMappingType.Decimal` to `107` | +| | `(Int32)OracleMappingType.Double` | `108` | Expression | [Casts][Explicit Casting] `OracleMappingType.Double` to `108` | +| | `(Int32)OracleMappingType.Long` | `109` | Expression | [Casts][Explicit Casting] `OracleMappingType.Long` to `109` | +| | `(Int32)OracleMappingType.LongRaw` | `110` | Expression | [Casts][Explicit Casting] `OracleMappingType.LongRaw` to `110` | +| | `(Int32)OracleMappingType.Int16` | `111` | Expression | [Casts][Explicit Casting] `OracleMappingType.Int16` to `111` | +| | `(Int32)OracleMappingType.Int32` | `112` | Expression | [Casts][Explicit Casting] `OracleMappingType.Int32` to `112` | +| | `(Int32)OracleMappingType.Int64` | `113` | Expression | [Casts][Explicit Casting] `OracleMappingType.Int64` to `113` | +| | `(Int32)OracleMappingType.IntervalDS` | `114` | Expression | [Casts][Explicit Casting] `OracleMappingType.IntervalDS` to `114` | +| | `(Int32)OracleMappingType.IntervalYM` | `115` | Expression | [Casts][Explicit Casting] `OracleMappingType.IntervalYM` to `115` | +| | `(Int32)OracleMappingType.NClob` | `116` | Expression | [Casts][Explicit Casting] `OracleMappingType.NClob` to `116` | +| | `(Int32)OracleMappingType.NChar` | `117` | Expression | [Casts][Explicit Casting] `OracleMappingType.NChar` to `117` | +| | `(Int32)OracleMappingType.NVarchar2` | `119` | Expression | [Casts][Explicit Casting] `OracleMappingType.NVarchar2` to `119` | +| | `(Int32)OracleMappingType.Raw` | `120` | Expression | [Casts][Explicit Casting] `OracleMappingType.Raw` to `120` | +| | `(Int32)OracleMappingType.RefCursor` | `121` | Expression | [Casts][Explicit Casting] `OracleMappingType.RefCursor` to `121` | +| | `(Int32)OracleMappingType.Single` | `122` | Expression | [Casts][Explicit Casting] `OracleMappingType.Single` to `122` | +| | `(Int32)OracleMappingType.TimeStamp` | `123` | Expression | [Casts][Explicit Casting] `OracleMappingType.TimeStamp` to `123` | +| | `(Int32)OracleMappingType.TimeStampLTZ` | `124` | Expression | [Casts][Explicit Casting] `OracleMappingType.TimeStampLTZ` to `124` | +| | `(Int32)OracleMappingType.TimeStampLZ` | `125` | Expression | [Casts][Explicit Casting] `OracleMappingType.TimeStampLZ` to `125` | +| | `(Int32)OracleMappingType.Varchar2` | `126` | Expression | [Casts][Explicit Casting] `OracleMappingType.Varchar2` to `126` | +| | `(Int32)OracleMappingType.XmlType` | `127` | Expression | [Casts][Explicit Casting] `OracleMappingType.XmlType` to `127` | +| | `(Int32)OracleMappingType.BinaryDouble` | `132` | Expression | [Casts][Explicit Casting] `OracleMappingType.BinaryDouble` to `132` | +| | `(Int32)OracleMappingType.BinaryFloat` | `133` | Expression | [Casts][Explicit Casting] `OracleMappingType.BinaryFloat` to `133` | +| Use `Convert.ToInt32` | `Convert.ToInt32(OracleMappingType.BFile)` | `101` | Expression | Converts `OracleMappingType.BFile` to `101`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Blob)` | `102` | Expression | Converts `OracleMappingType.Blob` to `102`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Byte)` | `103` | Expression | Converts `OracleMappingType.Byte` to `103`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Char)` | `104` | Expression | Converts `OracleMappingType.Char` to `104`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Clob)` | `105` | Expression | Converts `OracleMappingType.Clob` to `105`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Date)` | `106` | Expression | Converts `OracleMappingType.Date` to `106`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Decimal)` | `107` | Expression | Converts `OracleMappingType.Decimal` to `107`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Double)` | `108` | Expression | Converts `OracleMappingType.Double` to `108`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Long)` | `109` | Expression | Converts `OracleMappingType.Long` to `109`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.LongRaw)` | `110` | Expression | Converts `OracleMappingType.LongRaw` to `110`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Int16)` | `111` | Expression | Converts `OracleMappingType.Int16` to `111`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Int32)` | `112` | Expression | Converts `OracleMappingType.Int32` to `112`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Int64)` | `113` | Expression | Converts `OracleMappingType.Int64` to `113`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.IntervalDS)` | `114` | Expression | Converts `OracleMappingType.IntervalDS` to `114`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.IntervalYM)` | `115` | Expression | Converts `OracleMappingType.IntervalYM` to `115`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.NClob)` | `116` | Expression | Converts `OracleMappingType.NClob` to `116`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.NChar)` | `117` | Expression | Converts `OracleMappingType.NChar` to `117`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.NVarchar2)` | `119` | Expression | Converts `OracleMappingType.NVarchar2` to `119`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Raw)` | `120` | Expression | Converts `OracleMappingType.Raw` to `120`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.RefCursor)` | `121` | Expression | Converts `OracleMappingType.RefCursor` to `121`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Single)` | `122` | Expression | Converts `OracleMappingType.Single` to `122`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.TimeStamp)` | `123` | Expression | Converts `OracleMappingType.TimeStamp` to `123`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.TimeStampLTZ)` | `124` | Expression | Converts `OracleMappingType.TimeStampLTZ` to `124`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.TimeStampLZ)` | `125` | Expression | Converts `OracleMappingType.TimeStampLZ` to `125`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.Varchar2)` | `126` | Expression | Converts `OracleMappingType.Varchar2` to `126`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.XmlType)` | `127` | Expression | Converts `OracleMappingType.XmlType` to `127`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.BinaryDouble)` | `132` | Expression | Converts `OracleMappingType.BinaryDouble` to `132`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(OracleMappingType.BinaryFloat)` | `133` | Expression | Converts `OracleMappingType.BinaryFloat` to `133`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `OracleMappingType`. +- The Literal Editor is available for [Input][] properties where the data type is `OracleMappingType`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `OracleMappingType`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [OracleParameter][] +- [OracleParameters][] +- [OracleConnectionDetails][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[OracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/oracleparameter.md b/content/en/docs/2024.9/Reference/data-types/data/oracleparameter.md new file mode 100644 index 000000000..4a2187170 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/oracleparameter.md @@ -0,0 +1,172 @@ +--- +title: "OracleParameter" +linkTitle: "OracleParameter" +description: "Defines a type of parameter that can be run as part of a Command." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.OracleParameter)

+ +## Summary + +The `OracleParameter` data type is used to define a parameter for the [OracleConnectionDetails][] within the [Parameters property][ParametersProperty] on the [DataCommand][] data types. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `OracleParameter` | +| **Full Name:** | `Cortex.DataTypes.Data.OracleParameter` | +| **Alias:** | N/A | +| **Description:** | Defines a type of parameter that can be run as part of a Command. | +| **Default Value:** | `null` | +| **Can be used as:** | `OracleParameter`, `IParameter`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Name + +The name of the parameter that is being defined. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [string][] with value `$@""` | + +### Value + +The value of the parameter that is being defined. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +### Type + +The type of the parameter that is being defined. + +| | | +|--------------------|---------------------------| +| Data Type | [OracleMappingType][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [OracleMappingType][] with value `OracleMappingType.BFile` | + +### ParameterDirection + +The direction of the parameter that is being defined. + +| | | +|--------------------|---------------------------| +| Data Type | [ParameterDirection][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [ParameterDirection][] with value `ParameterDirection.Input` | + +### Size + +The size of the parameter that is being defined. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +## Remarks + +### Create an OracleParameter + +The following table shows some of the ways that an `OracleParameter` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `OracleParameter` constructor | `new OracleParameter("name", $@"", OracleMappingType.Clob, ParameterDirection.Input, 0)` | `{Name: "name", Value: $@"value", Type: OracleMappingType.Clob, Direction: ParameterDirection.Input, Size: 0}` | Expression | | + +### Convert OracleParameter to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)OracleParameter.ToString()` | `"Cortex.DataTypes.Data.OracleParameter"` | Expression | ToString will return the Full Name of the OracleParameter Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{name: "name", value: $@"value", type: OracleMappingType.Clob, direction: ParameterDirection.Input, size: 0}` | `"Cortex.DataTypes.Data.OracleParameter"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{name: "name", value: $@"value", type: OracleMappingType.Clob, direction: ParameterDirection.Input, size: 0}` | `"{\r\n \"Name\": \"name\",\r\n \"Value\": \"value\",\r\n \"Type\": 105,\r\n \"Direction\": 1,\r\n \"Size\": 0}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `OracleParameter`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `OracleParameter`. + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on an `OracleParameter`, then its Full Name will be returned; instead of a representation of the data within the `Command`. + +In future this limitation may be removed. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] +* [OracleParameters][] +* [OracleConnectionDetails][] +* [OracleMappingType][] +* [IParameter][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [ParameterDirection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Statements]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.Statements" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} +[CommandExceptionIncompatibleStatementType]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.IncompatibleStatementType" >}} +[ConnectionDetailsProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ConnectionDetailsProperty" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} + +[ParameterDirection]: {{< url path="OracleParameter.ParameterDirection" >}} +[OracleMappingType]: {{< url path="Cortex.Reference.DataTypes.Data.OracleMappingType.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[OracleParameters]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameters.MainDoc" >}} +[IParameter]: {{< url path="Cortex.Reference.DataTypes.Data.IParameter.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/oracleparameters.md b/content/en/docs/2024.9/Reference/data-types/data/oracleparameters.md new file mode 100644 index 000000000..2e3a6792a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/oracleparameters.md @@ -0,0 +1,134 @@ +--- +title: "OracleParameters" +linkTitle: "OracleParameters" +description: "Defines a type of parameter that can be run as part of a Command." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.OracleParameters)

+ +## Summary + +The `OracleParameters` data type is used to define multiple parameters for the [OracleConnectionDetails][] within the [Parameters property][ParametersProperty] on the [DataCommand][] data types. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `OracleParameters` | +| **Full Name:** | `Cortex.DataTypes.Data.OracleParameters` | +| **Alias:** | N/A | +| **Description:** | Defines a type of parameter that can be run as part of a Command. | +| **Default Value:** | `null` | +| **Can be used as:** | `OracleParameters`, `IParameters`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Basic + +Parameters that will be processed with only a name and value. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +### Advanced + +Parameters that will be processed with a name, value, type, direction and size. + +| | | +|--------------------|---------------------------| +| Data Type | [IEnumberable][]<[OracleParameter][]> | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [IEnumberable][]<[OracleParameter][]> with no value | + +## Remarks + +### Create an OracleParameters + +The following table shows some of the ways that an `OracleParameters` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `OracleParameters` constructor | `new OracleParameters(new {parameterName = "parameterValue",}, new List(){ new OracleParameter("name", $@"", OracleMappingType.Clob, ParameterDirection.Input, 0), })` | `{"Basic": {"parameterName": "parameterValue"},"Advanced": [{"Name": "name","Value": "","Type": "OracleMappingType.Clob","Direction": "ParameterDirection.Input","Size": 0}]}` | Expression | | + +### Convert OracleParameters to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)OracleParameters.ToString()` | `"Cortex.DataTypes.Data.OracleParameters"` | Expression | ToString will return the Full Name of the OracleParameters Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{"Basic": {"parameterName": "parameterValue"},"Advanced": [{"Name": "name","Value": "","Type": "OracleMappingType.Clob","Direction": "ParameterDirection.Input","Size": 0}]}` | `"Cortex.DataTypes.Data.OracleParameters"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Basic": {"parameterName": "parameterValue"},"Advanced": [{"Name": "name","Value": "","Type": "OracleMappingType.Clob","Direction": "ParameterDirection.Input","Size": 0}]}` | `"{"Basic": {"parameterName": "parameterValue"},"Advanced": [{"Name": "name","Value": "","Type": 105,"Direction": 1,"Size": 0}]}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `OracleParameters`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `OracleParameters`. + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `OracleParameters`, then its Full Name will be returned; instead of a representation of the data within the `Command`. + +In future this limitation may be removed. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Commands][] +* [QueryCommand][] +* [NonQueryCommand][] +* [OracleParameter][] +* [OracleConnectionDetails][] +* [IParameters<T>][IParameters] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* None + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Statements]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.Statements" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[QueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.QueryCommand.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[CommandException]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.MainDoc" >}} +[CommandExceptionIncompatibleStatementType]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.IncompatibleStatementType" >}} +[ConnectionDetailsProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ConnectionDetailsProperty" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[IEnumberable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[ParametersProperty]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.Parameters" >}} +[OracleParameter]: {{< url path="Cortex.Reference.DataTypes.Data.OracleParameter.MainDoc" >}} +[IParameters]: {{< url path="Cortex.Reference.DataTypes.Data.IParameters.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/querycommand.md b/content/en/docs/2024.9/Reference/data-types/data/querycommand.md new file mode 100644 index 000000000..4aa4eb394 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/querycommand.md @@ -0,0 +1,152 @@ +--- +title: "QueryCommand" +linkTitle: "QueryCommand" +description: "Holds the information for running a Query command against a data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.QueryCommand)

+ +## Summary + +A `QueryCommand` data type is used to define single or multiple [Query Statements][Query Statement] that can be run against a data source. Statements can be [parameterised][Parameterised Commands], which is recommended to prevent [SQL Injection][]. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `QueryCommand` | +| **Full Name:** | `Cortex.DataTypes.Data.QueryCommand` | +| **Alias:** | N/A | +| **Description:** | Defines single or multiple Query Statements that can be run against a data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `DataCommand`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Command Text + +The Command Text is used to define single or multiple [Query Statements][Query Statement] that will be run against the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Parameters + +Parameters are used to pass information to the [Query Statements][Query Statement] that will be run against the data source. + +It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +For more information see [Parameterised Commands][]. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is Advanced | `true` | +| Default Editor | [Expression][] | +| Default Value | [dynamic][] with no value | + +## Remarks + +### Create a QueryCommand + +The following table shows some of the ways that a `QueryCommand` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `QueryCommand` constructor | `new QueryCommand("SELECT * FROM Table", null)` | `{CommandText: "SELECT * FROM Table", Parameters: null}` | Expression | | +| | `new QueryCommand("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3})` | `{"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}}` | Expression | It is recommended to always use [Parameterised Commands][] as they prevent [SQL Injection][] | + +A `QueryCommand` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `CommandText`| `EncryptableText`| `$@"SELECT * FROM Table WHERE Id < @SelectParameter"` | The command that will be queried against the data source. | +| `Parameters`| `dynamic`| `new { SelectParameter = 3 })` | The parameters that are used within a [Parameterised Command][Parameterised Commands]. | + +### Convert QueryCommand to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)QueryCommand.ToString()` | `"Cortex.DataTypes.Data.QueryCommand"` | Expression | ToString will return the Full Name of the QueryCommand Data Type | +| Use `Convert Object To Text` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"Cortex.DataTypes.Data.QueryCommand"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `{CommandText: "SELECT * FROM Table", Parameters: null}` | `"{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Parameterised Commands + +It is recommended to always use parameterised commands as they prevent [SQL Injection][] attacks by ensuring the parameters are sanitised before the command is executed. + +The `@` symbol denotes a parameter within the [CommandText][] (e.g. `"SELECT * FROM Table WHERE Name = @Parameter"`). An example of using parameters can be found in [Executing Multiple Commands (Safe)][], whereas, an example of inserting variables into a statement without parameters can be found in [Executing Multiple Commands (Unsafe)][] + +For more information see [Parameterised Commands][Block: Parameterised Commands]. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `QueryCommand`. +* The Literal Editor is available for [Input][] properties where the data type is `QueryCommand`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `QueryCommand`. + +### Known limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `QueryCommand`, then its Full Name will be returned; instead of a representation of the data within the `QueryCommand`. + +In future this limitation may be removed. + +#### Multiple SQL Commands (Oracle Only) + +For Oracle you must use [block statement syntax][OracleBlockStatement] to execute multiple commands, otherwise a [CommandException][CommandExceptionRuntime] will be thrown. + +## See Also + +### Related Data Types + +* [DataCommand][] +* [Command][] +* [Commands][] +* [NonQueryCommand][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [OracleBlockStatement][] +* [SQL Injection][] + +[CommandText]: {{< ref "#command-text" >}} +[Parameterised Commands]: {{< ref "#parameterised-commands" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Executing Multiple Commands (Safe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsSafe" >}} +[Executing Multiple Commands (Unsafe)]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ExecutingMultipleCommandsUnsafe" >}} +[Block: Parameterised Commands]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.ParameterisedCommands" >}} +[Query Statement]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.QueryStatements" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[DataCommand]: {{< url path="Cortex.Reference.DataTypes.Data.DataCommand.MainDoc" >}} +[Command]: {{< url path="Cortex.Reference.DataTypes.Data.Command.MainDoc" >}} +[Commands]: {{< url path="Cortex.Reference.DataTypes.Data.Commands.MainDoc" >}} +[NonQueryCommand]: {{< url path="Cortex.Reference.DataTypes.Data.NonQueryCommand.MainDoc" >}} +[CommandProperty]: {{< url path="Cortex.Reference.Blocks.Data.ExecuteDataCommand.ExecuteDataCommand.CommandProperty" >}} +[CommandExceptionRuntime]: {{< url path="Cortex.Reference.Exceptions.Data.CommandException.Runtime" >}} + +[OracleBlockStatement]: {{< url path="Oracle.PL-SQL.BlockStatement" >}} +[SQL Injection]: {{< url path="W3.SqlInjection" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/data/sqlserverconnectiondetails.md b/content/en/docs/2024.9/Reference/data-types/data/sqlserverconnectiondetails.md new file mode 100644 index 000000000..29d0e3856 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/data/sqlserverconnectiondetails.md @@ -0,0 +1,102 @@ +--- +title: "SqlServerConnectionDetails" +linkTitle: "SqlServerConnectionDetails" +description: "The data type representing configuration for establishing and maintaining a connection to an SQL Server data source." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Data.SqlServerConnectionDetails)

+ +## Summary + +The `SqlServerConnectionDetails` data type is used to establish and maintain a connection to a SQL Server data source. + +| | | +|-|-| +| **Category:** | Data | +| **Name:** | `SqlServerConnectionDetails` | +| **Full Name:** | `Cortex.DataTypes.Data.SqlServerConnectionDetails` | +| **Alias:** | N/A | +| **Description:** | The data type representing configuration for establishing and maintaining a connection to an SQL Server data source. | +| **Default Value:** | `null` | +| **Can be used as:** | `ConnectionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Connection String + +The Connection String that is used to connect to the data source. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is Advanced | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@"Server=localhost;Database=YourDatabase;Trusted_Connection=true;"` | + +## Remarks + +### Create a SqlServerConnectionDetails + +The following table shows some of the ways that a `SqlServerConnectionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `SqlServerConnectionDetails` constructor | `new SqlServerConnectionDetails("Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;")` | `{"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"}` | Expression | | + +A `SqlServerConnectionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Connection String`| `EncryptableText`| `$@"Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"` | The Connection String that is used to connect to the data source. | + +### Connection Strings + +A [Connection String][] must be provided in order to connect to a SQL Server data source. The [Connection String][] can be formatted differently depending either on the version of SQL Server or the way the connection will be created and maintained (e.g. Trusted connection vs explicit user). See [ConnectionStrings.com][] for a list of connection strings for SQL Server. + +Please see [Working with Data Sources][] for a list of other supported data sources (e.g. ODBC) and how to construct valid connection strings for them. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `SqlServerConnectionDetails`. +* The Literal Editor is not available for [Input][] properties where the data type is `SqlServerConnectionDetails`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SqlServerConnectionDetails`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +* [ConnectionDetails][] +* [OdbcConnectionDetails][] +* [OracleConnectionDetails][] + +### Related Concepts + +* [Working with Data Sources][] + +### External Documentation + +* [ConnectionStrings.com][] + +[Connection String]: {{< ref "#connection-string" >}} + +[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" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[ConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.ConnectionDetails.MainDoc" >}} +[OdbcConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OdbcConnectionDetails.MainDoc" >}} +[OracleConnectionDetails]: {{< url path="Cortex.Reference.DataTypes.Data.OracleConnectionDetails.MainDoc" >}} + +[Working with Data Sources]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DataSources.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} + +[ConnectionStrings.com]: {{< url path="ConnectionStrings.SqlConnection" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/_index.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/_index.md new file mode 100644 index 000000000..12482d669 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/_index.md @@ -0,0 +1,6 @@ +--- +title: "Date & Time" +linkTitle: "Date & Time" +description: "Data types used for working with dates and time." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/datetime.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetime.md new file mode 100644 index 000000000..2d46248ad --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetime.md @@ -0,0 +1,133 @@ +--- +title: "DateTime" +linkTitle: "DateTime" +description: "Used to represent a date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar. It can be used wherever a `DateTimeOffset` is expected, and will be implicitly cast." +--- + +# {{% param title %}} + +

(System.DateTime)

+ +## Summary + +The `DateTime` data type is used to represent a date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar. It can be used wherever a [DateTimeOffset][] is expected, and will be [implicitly cast][Implicit Casting]. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `DateTime` | +| **Full Name:** | `System.DateTime` | +| **Alias:** | N/A | +| **Description:** | A date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar. It can be used wherever a [DateTimeOffset][] is expected, and will be [implicitly cast][Implicit Casting]. | +| **Size:** | Varies, typically `8` bytes | +| **Default Value:** | `0001-01-01T00:00:00` (i.e. [DateTime.MinValue][]) | +| **Can be used as:** | `DateTimeOffset`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a DateTime + +The following table shows some of the ways that a `DateTime` can be created. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `DateTime.Now` | `DateTime.Now` | `2022-07-01T14:00:00.0000000+01:00` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as local time. See [DateTime.Now][] | +| Use `DateTime.UtcNow` | `DateTime.UtcNow` | `2022-07-01T13:00:00.0000000Z` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC). See [DateTime.UtcNow][] | +| Use `DateTime.Parse`| `DateTime.Parse("1/7/2022 2:00:00 PM")` | `2022-07-01T14:00:00` | Expression | Parses a date string and converts it to a `DateTime` using the [current culture][] of the system. In this example it parses `"1/7/2022 2:00:00 PM"` using `en-GB` [culture][] and converts it to `2022-07-01T14:00:00`. See [DateTime.Parse][] | +| Use a `DateTime` constructor | `new DateTime(2022, 7, 1, 14, 0, 0, 0)` | `2022-07-01T14:00:00` | Expression | `2PM 1st July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). See [DateTime Constructors][]. | +| Use `DateTimeOffset.DateTime` | `DateTimeOffset.UtcNow.DateTime` | `2022-07-01T13:00:00.0000000` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` using the date and time components, but not the offset. See [DateTimeOffset.DateTime][] | +| Use `DateTimeOffset.LocalDateTime` | `DateTimeOffset.UtcNow.LocalDateTime` | `2022-07-01T14:00:00.0000000+01:00` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` relative to the local time. See [DateTimeOffset.LocalDateTime][] | +| Use `DateTimeOffset.UtcDateTime` | `DateTimeOffset.UtcNow.UtcDateTime` | `2022-07-01T13:00:00.0000000Z` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` relative to Coordinated Universal Time (UTC). See [DateTimeOffset.UtcDateTime][] | + +Please see [Initializing a DateTime object][] for further information. + +### Convert DateTime to Text + +The following table shows some of the ways that a `DateTime` can be converted to text. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `DateTime.UtcNow.ToString()` | `"1/7/2022 1:00:00 PM"` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][] and the [long time pattern][StandardFormatTemplates] for the [current culture][] with each element separated from the previous element by a space. See [DateTime.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(DateTime.UtcNow)` | `"1/7/2022 1:00:00 PM"` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][] and the [long time pattern][StandardFormatTemplates] for the [current culture][], with each element separated from the previous element by a space. See [Convert.ToString][] | +| Use `Convert DateTime To Text` block | where `Date Time` property has a value of `DateTime.UtcNow` | `"2022-07-01T13:00:00.0000000+00:00"` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use [ISO 8601 Standard][] format for `DateTimeOffset` (i.e. `yyyy-MM-ddTHH:mm:ss.fffffffzzz`) as the `Convert DateTime To Text` block will impicitly convert a `DateTime` to a `DateTimeOffset`. See [Convert DateTime To Text][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `DateTime.UtcNow` | `"1/7/2022 1:00:00 PM"` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][] and the [long time pattern][StandardFormatTemplates] for the [current culture][], with each element separated from the previous element by a space. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `DateTime.UtcNow` | `"\"2022-07-01T13:00:00.0000000Z\""` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use [ISO 8601 Standard][] format for `DateTime` (i.e. `yyyy-MM-ddTHH:mm:ss.fffffffK`). See [Convert Object To Json][] | + +Please see [Date and Time Formatting][] for further information on formatting `DateTime` values, including how [Operating System Settings][] can affect the [current culture][]. + +### Convert DateTime to a DateTimeOffset + +`DateTime` values will be [implicitly cast][Implicit Casting] to [DateTimeOffset][] values if used where a [DateTimeOffset][] is expected. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `DateTime`. +* The Literal Editor is available for [Input][] properties where the data type is `DateTime`. + * Expression syntax is not supported within the Literal Editor for the `DateTime` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `DateTime`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [DateTimeOffset][] + +### Related Concepts + +* [Working with Date and Time][] +* [Implicit Casting][] +* [Culture][] + +### External Documentation + +* [System.DateTime][] + +[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" >}} + +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[Convert Text To DateTime]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTime.MainDoc" >}} +[Convert DateTime To Text]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertDateTimeToText.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Initializing a DateTime object]: {{< url path="MSDocs.DotNet.Api.System.DateTime.InitializingADateTimeObject" >}} + +[System.DateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTime.MainDoc" >}} +[DateTime Constructors]: {{< url path="MSDocs.DotNet.Api.System.DateTime.Ctors" >}} +[DateTime.MinValue]: {{< url path="MSDocs.DotNet.Api.System.DateTime.MinValue" >}} +[DateTime.Now]: {{< url path="MSDocs.DotNet.Api.System.DateTime.Now" >}} +[DateTime.UtcNow]: {{< url path="MSDocs.DotNet.Api.System.DateTime.UtcNow" >}} +[DateTime.Parse]: {{< url path="MSDocs.DotNet.Api.System.DateTime.Parse" >}} +[DateTime.ToString]: {{< url path="MSDocs.DotNet.Api.System.DateTime.ToString" >}} + +[DateTimeOffset.DateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.DateTime" >}} +[DateTimeOffset.LocalDateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.LocalDateTime" >}} +[DateTimeOffset.UtcDateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.UtcDateTime" >}} + +[Date and Time Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.MainDoc" >}} +[StandardFormatTemplates]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.StandardFormatTemplates" >}} +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Operating System Settings]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.OperatingSystemSettings" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} +[TimeSpan]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimeSpan.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.MainDoc" >}} +[Current Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.CurrentCulture.MainDoc" >}} + +[Implicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ImplicitCast" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimecomponenttype.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimecomponenttype.md new file mode 100644 index 000000000..355ac96d6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimecomponenttype.md @@ -0,0 +1,74 @@ +--- +title: "DateTimeComponentType" +linkTitle: "DateTimeComponentType" +description: "Used to represent a component of a `DateTimeOffset` (e.g. `Year`, `Month`, `Day`)." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.DateAndTime.DateTimeComponentType)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `DateTimeComponentType` data type is used to represent a component of a `DateTimeOffset` (e.g. `Year`, `Month`, `Day`). + +`DateTimeComponentType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `DateTimeComponentType` | +| **Full Name:** | `Cortex.DataTypes.DateAndTime.DateTimeComponentType` | +| **Alias:** | N/A | +| **Description:** | Used to represent a component of a `DateTimeOffset` (e.g. `Year`, `Month`, `Day`). | +| **Default Value:** | `(DateTimeComponentType)0` | +| **Can be used as:** | `DateTimeComponentType`, `object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)DateTimeComponentType.LocalDateTime` or `(System.Int16)DateTimeComponentType.LocalDateTime` or `(short)DateTimeComponentType.LocalDateTime`) | +| | `Int32` (e.g. `(Int32)DateTimeComponentType.LocalDateTime` or `(System.Int32)DateTimeComponentType.LocalDateTime` or `(int)DateTimeComponentType.LocalDateTime`) | +| | `Int64` (e.g. `(Int64)DateTimeComponentType.LocalDateTime` or `(System.Int64)DateTimeComponentType.LocalDateTime` or `(long)DateTimeComponentType.LocalDateTime`) | +| | `Single` (e.g. `(Single)DateTimeComponentType.LocalDateTime` or `(System.Single)DateTimeComponentType.LocalDateTime` or `(float)DateTimeComponentType.LocalDateTime`) | +| | `Double` (e.g. `(Double)DateTimeComponentType.LocalDateTime` or `(System.Double)DateTimeComponentType.LocalDateTime` or `(double)DateTimeComponentType.LocalDateTime`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `DateTimeComponentType`. +- The Literal Editor is available for [Input][] properties where the data type is `DateTimeComponentType`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `DateTimeComponentType`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [DateTimeOffset][] + +### Related Concepts + +- [Working with Date and Time][] + +### External Documentation + +- [System.DateTimeOffset][] +- [System.Enum][] + +[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" >}} + +[DateTimeOffset]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTimeOffset.MainDoc" >}} + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} +[System.DateTimeOffset]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.MainDoc" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimeoffset.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimeoffset.md new file mode 100644 index 000000000..9aa34a82f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/datetimeoffset.md @@ -0,0 +1,157 @@ +--- +title: "DateTimeOffset" +linkTitle: "DateTimeOffset" +description: "Used to represent a date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar, along with a UTC time offset." +--- + +# {{% param title %}} + +

(System.DateTimeOffset)

+ +## Summary + +The `DateTimeOffset` data type is used to represent a date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar, along with a UTC time offset. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `DateTimeOffset` | +| **Full Name:** | `System.DateTimeOffset` | +| **Alias:** | N/A | +| **Description:** | A date and time between `00:00:00.0000000 UTC, January 1, 0001` and `23:59:59.9999999 UTC, December 31, 9999`, in the Gregorian calendar, along with a UTC time offset. | +| **Size:** | Varies, typically `12` to `16` bytes | +| **Default Value:** | `0001-01-01T00:00:00+00:00` (i.e. [DateTimeOffset.MinValue][])| +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a DateTimeOffset + +The following table shows some of the ways that a `DateTimeOffset` can be created. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `DateTimeOffset.Now` | `DateTimeOffset.Now` | `2022-07-01T14:00:00.0000000+01:00` | Expression | The result shown is an example result. The actual result will show the current date and time on the current computer, with the offset set to the local time's offset from Coordinated Universal Time (UTC). See [DateTimeOffset.Now][]. | +| Use `DateTimeOffset.UtcNow` | `DateTimeOffset.UtcNow` | `2022-07-01T13:00:00.0000000+00:00` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero. See [DateTimeOffset.UtcNow][]. | +| [Implicit Casting][] of [DateTime][] | `DateTime.UtcNow` | `2022-07-01T13:00:00.0000000+00:00` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero. | +| Use `DateTimeOffset.Parse`| `DateTimeOffset.Parse("1/7/2022 2:00:00 PM +1:00")` | `2022-07-01T14:00:00+01:00` | Expression | Parses a date string and converts it to a `DateTimeOffset` using the [current culture][] of the system. In this example it parses `"1/7/2022 2:00:00 PM +1:00"` using `en-GB` [culture][] and converts it to `2022-07-01T14:00:00+01:00`. See [DateTimeOffset.Parse][] | +| Use a `DateTimeOffset` constructor | `new DateTimeOffset(2022, 7, 1, 14, 0, 0, 0, new TimeSpan(1, 0, 0))` | `2022-07-01T14:00:00+01:00` | Expression | `2PM 1st July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). See [DateTimeOffset Constructors][]. | +| Use `Convert Text To DateTime` block | where `Text` property has a value of `"1/7/2022 2:00:00 PM +1:00"` | `2022-07-01T14:00:00+01:00` | Expression | Parses a date string and converts it to a `DateTimeOffset`. See [Convert Text To DateTime][] | + +Please see [Instantiating a DateTimeOffset object][] for further information. + +A `DateTimeOffset` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Notes | +|-|-|-| +| `Year` | `Int32` | The year expressed as an [Int32][] value between `1` and `9999`. | +| `Month` | `Int32` | The month expressed as an [Int32][] value between `1` and `12`. | +| `Day` | `Int32` | The day expressed as an [Int32][] value between `1` and the number of days in `Month`. | +| `Hour` | `Int32` | The hour expressed as an [Int32][] value between `0` and `23`. | +| `Minute` | `Int32` | The minute expressed as an [Int32][] value between `0` and `59`. | +| `Second` | `Int32` | The second expressed as an [Int32][] value between `0` and `59`. | +| `Millisecond` | `Int32` | The millisecond expressed as an [Int32][] value between `0` and `999`.| +| `Offset` | `TimeSpan`| The UTC Offset expressed as a [TimeSpan][] value between `-14` hours and `14` hours. This is calculated as the sum of `Offset.Days + Offset.Hours + Offset.Minutes + Offset.Seconds + Offset.Milliseconds`. If the value is outside `-14` hours and `14` hours an [InvalidPropertyValueException][] will be thrown. | + +### Convert DateTimeOffset to Text + +The following table shows some of the ways that a `DateTimeOffset` can be converted to text. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `DateTimeOffset.UtcNow.ToString()` | `"1/7/2022 1:00:00 PM +00:00"` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][], the [long time pattern][StandardFormatTemplates] for the [current culture][], and the `zzz` [custom format string][CustomFormatTemplates], with each element separated from the previous element by a space. See [DateTimeOffset.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(DateTimeOffset.UtcNow)` | `"1/7/2022 1:00:00 PM +00:00"` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][], the [long time pattern][StandardFormatTemplates] for the [current culture][], and the `zzz` [custom format string][CustomFormatTemplates], with each element separated from the previous element by a space. See [Convert.ToString][] | +| Use `Convert DateTime To Text` block | where `Date Time` property has a value of `DateTimeOffset.UtcNow` | `"2022-07-01T13:00:00.0000000+00:00"` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use [ISO 8601 Standard][] format for `DateTimeOffset` (i.e. `yyyy-MM-ddTHH:mm:ss.fffffffzzz`). See [Convert DateTime To Text][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `DateTimeOffset.UtcNow` | `"1/7/2022 1:00:00 PM +00:00"` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the [short date pattern][StandardFormatTemplates] for the [current culture][], the [long time pattern][StandardFormatTemplates] for the [current culture][], and the `zzz` [custom format string][CustomFormatTemplates], with each element separated from the previous element by a space. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `DateTimeOffset.UtcNow` | `"\"2022-07-01T13:00:00.0000000+00:00\""` | Expression | The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use [ISO 8601 Standard][] format for `DateTimeOffset` (i.e. `yyyy-MM-ddTHH:mm:ss.fffffffzzz`). See [Convert Object To Json][] | + +Please see [Date and Time Formatting][] for further information on formatting `DateTimeOffset` values, including how [Operating System Settings][] can affect the [current culture][]. + +### Convert DateTimeOffset to a DateTime + +The following table shows some of the ways that a `DateTimeOffset` can be converted to a `DateTime`. + +All examples are for a system configured with British [culture][] (i.e. `en-GB`), and use a local time of `2PM 1st of July 2022` with `1` hour UTC offset, honouring British Summer Time (BST). + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `DateTimeOffset.DateTime` | `DateTimeOffset.UtcNow.DateTime` | `2022-07-01T13:00:00.0000000` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` using the date and time components, but not the offset. See [DateTimeOffset.DateTime][] | +| Use `DateTimeOffset.LocalDateTime` | `DateTimeOffset.UtcNow.LocalDateTime` | `2022-07-01T14:00:00.0000000+01:00` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` relative to the local time. See [DateTimeOffset.LocalDateTime][] | +| Use `DateTimeOffset.UtcDateTime` | `DateTimeOffset.UtcNow.UtcDateTime` | `2022-07-01T13:00:00.0000000Z` | Expression | Converts `DateTimeOffset.UtcNow` to a `DateTime` relative to Coordinated Universal Time (UTC). See [DateTimeOffset.UtcDateTime][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `DateTimeOffset`. +* The Literal Editor is available for [Input][] properties where the data type is `DateTimeOffset`. + * Expression syntax is not supported within the Literal Editor for the `DateTimeOffset` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `DateTimeOffset`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [DateTime][] +* [TimeSpan][] + +### Related Concepts + +* [Working with Date and Time][] +* [Implicit Casting][] +* [Culture][] + +### External Documentation + +* [System.DateTimeOffset][] + +[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" >}} + +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[Instantiating a DateTimeOffset object]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.InstantiatingADateTimeOffsetObject" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[Convert Text To DateTime]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTime.MainDoc" >}} +[Convert DateTime To Text]: {{< url path="Cortex.Reference.Blocks.DateAndTime.ConvertDateTime.ConvertDateTimeToText.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[System.DateTimeOffset]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.MainDoc" >}} +[DateTimeOffset Constructors]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.Ctors" >}} +[DateTimeOffset.MinValue]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.MinValue" >}} +[DateTimeOffset.Parse]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.Parse" >}} +[DateTimeOffset.Now]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.Now" >}} +[DateTimeOffset.UtcNow]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.UtcNow" >}} +[DateTimeOffset.DateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.DateTime" >}} +[DateTimeOffset.LocalDateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.LocalDateTime" >}} +[DateTimeOffset.UtcDateTime]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.UtcDateTime" >}} +[DateTimeOffset.ToString]: {{< url path="MSDocs.DotNet.Api.System.DateTimeOffset.ToString" >}} + +[Date and Time Formatting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.MainDoc" >}} +[StandardFormatTemplates]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.StandardFormatTemplates" >}} +[CustomFormatTemplates]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.CustomFormatTemplates" >}} +[ISO 8601 Standard]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.ISO8601Standard" >}} +[Operating System Settings]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.DateAndTimeFormatting.OperatingSystemSettings" >}} + +[DateTime]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.DateTime.MainDoc" >}} +[TimeSpan]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimeSpan.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.MainDoc" >}} +[Current Culture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Culture.CurrentCulture.MainDoc" >}} + +[Implicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ImplicitCast" >}} + +[InvalidPropertyValueException]: {{< url path="Cortex.Reference.Exceptions.Flows.Blocks.InvalidPropertyValueException.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/dayofweek.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/dayofweek.md new file mode 100644 index 000000000..66a2cdcc6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/dayofweek.md @@ -0,0 +1,193 @@ +--- +title: "DayOfWeek" +linkTitle: "DayOfWeek" +description: "Used to represent a day of the week from Sunday (i.e. `DayOfWeek.Sunday`) through Saturday (i.e. `DayOfWeek.Saturday`)." +--- + +# {{% param title %}} + +

(System.DayOfWeek)

+ +## Summary + +The `DayOfWeek` data type is used to represent a day of the week from Sunday (i.e. `DayOfWeek.Sunday`) through Saturday (i.e. `DayOfWeek.Saturday`). + +`DayOfWeek` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `DayOfWeek` | +| **Full Name:** | `System.DayOfWeek` | +| **Alias:** | N/A | +| **Description:** | A day of the week from Sunday (i.e. `DayOfWeek.Sunday`) through Saturday (i.e. `DayOfWeek.Saturday`). | +| **Size:** | `4` bytes | +| **Values:** | `DayOfWeek.Sunday` where name is `"Sunday"` and value is `0` | +| | `DayOfWeek.Monday` where name is `"Monday"` and value is `1` | +| | `DayOfWeek.Tuesday` where name is `"Tuesday"` and value is `2` | +| | `DayOfWeek.Wednesday` where name is `"Wednesday"` and value is `3` | +| | `DayOfWeek.Thursday` where name is `"Thursday"` and value is `4` | +| | `DayOfWeek.Friday` where name is `"Friday"` and value is `5` | +| | `DayOfWeek.Saturday` where name is `"Saturday"` and value is `6` | +| **Default Value:** | `DayOfWeek.Sunday` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)DayOfWeek.Sunday` or `(System.Int16)DayOfWeek.Sunday` or `(short)DayOfWeek.Sunday`) | +| | `Int32` (e.g. `(Int32)DayOfWeek.Sunday` or `(System.Int32)DayOfWeek.Sunday` or `(int)DayOfWeek.Sunday`) | +| | `Int64` (e.g. `(Int64)DayOfWeek.Sunday` or `(System.Int64)DayOfWeek.Sunday` or `(long)DayOfWeek.Sunday`) | +| | `Single` (e.g. `(Single)DayOfWeek.Sunday` or `(System.Single)DayOfWeek.Sunday` or `(float)DayOfWeek.Sunday`) | +| | `Double` (e.g. `(Double)DayOfWeek.Sunday` or `(System.Double)DayOfWeek.Sunday` or `(double)DayOfWeek.Sunday`) | + +## Remarks + +### Create a DayOfWeek + +The following table shows some of the ways that a `DayOfWeek` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `DayOfWeek` literal | `Sunday` | `DayOfWeek.Sunday` | Literal | Indicates Sunday | +| | `Monday` | `DayOfWeek.Monday` | Literal | Indicates Monday | +| | `Tuesday` | `DayOfWeek.Tuesday` | Literal | Indicates Tuesday | +| | `Wednesday` | `DayOfWeek.Wednesday` | Literal | Indicates Wednesday | +| | `Thursday` | `DayOfWeek.Thursday` | Literal | Indicates Thursday | +| | `Friday` | `DayOfWeek.Friday` | Literal | Indicates Friday | +| | `Saturday` | `DayOfWeek.Saturday` | Literal | Indicates Saturday | +| Use a `DayOfWeek` expression | `DayOfWeek.Sunday` | `DayOfWeek.Sunday` | Expression | Indicates Sunday | +| | `DayOfWeek.Monday` | `DayOfWeek.Monday` | Expression | Indicates Monday | +| | `DayOfWeek.Tuesday` | `DayOfWeek.Tuesday` | Expression | Indicates Tuesday | +| | `DayOfWeek.Wednesday` | `DayOfWeek.Wednesday` | Expression | Indicates Wednesday | +| | `DayOfWeek.Thursday` | `DayOfWeek.Thursday` | Expression | Indicates Thursday | +| | `DayOfWeek.Friday` | `DayOfWeek.Friday` | Expression | Indicates Friday | +| | `DayOfWeek.Saturday` | `DayOfWeek.Saturday` | Expression | Indicates Saturday | +| Use [Explicit Casting][] | `(DayOfWeek)0` | `DayOfWeek.Sunday` | Expression | [Casts][Explicit Casting] `0` to `DayOfWeek.Sunday` | +| | `(DayOfWeek)1` | `DayOfWeek.Monday` | Expression | [Casts][Explicit Casting] `1` to `DayOfWeek.Monday` | +| | `(DayOfWeek)2` | `DayOfWeek.Tuesday` | Expression | [Casts][Explicit Casting] `2` to `DayOfWeek.Tuesday` | +| | `(DayOfWeek)3` | `DayOfWeek.Wednesday` | Expression | [Casts][Explicit Casting] `3` to `DayOfWeek.Wednesday` | +| | `(DayOfWeek)4` | `DayOfWeek.Thursday` | Expression | [Casts][Explicit Casting] `4` to `DayOfWeek.Thursday` | +| | `(DayOfWeek)5` | `DayOfWeek.Friday` | Expression | [Casts][Explicit Casting] `5` to `DayOfWeek.Friday` | +| | `(DayOfWeek)6` | `DayOfWeek.Saturday` | Expression | [Casts][Explicit Casting] `6` to `DayOfWeek.Saturday` | +| Use `Enum.Parse` | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Sunday")` | `DayOfWeek.Sunday` | Expression | Parses `"Sunday"` and converts it to `DayOfWeek.Sunday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Monday")` | `DayOfWeek.Monday` | Expression | Parses `"Monday"` and converts it to `DayOfWeek.Monday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Tuesday")` | `DayOfWeek.Tuesday` | Expression | Parses `"Tuesday"` and converts it to `DayOfWeek.Tuesday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Wednesday")` | `DayOfWeek.Wednesday` | Expression | Parses `"Wednesday"` and converts it to `DayOfWeek.Wednesday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Thursday")` | `DayOfWeek.Thursday` | Expression | Parses `"Thursday"` and converts it to `DayOfWeek.Thursday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Friday")` | `DayOfWeek.Friday` | Expression | Parses `"Friday"` and converts it to `DayOfWeek.Friday`. See [Enum.Parse][] | +| | `(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Saturday")` | `DayOfWeek.Saturday` | Expression | Parses `"Saturday"` and converts it to `DayOfWeek.Saturday`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 0)` | `DayOfWeek.Sunday` | Expression | Converts `0` to `DayOfWeek.Sunday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 1)` | `DayOfWeek.Monday` | Expression | Converts `1` to `DayOfWeek.Monday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 2)` | `DayOfWeek.Tuesday` | Expression | Converts `2` to `DayOfWeek.Tuesday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 3)` | `DayOfWeek.Wednesday` | Expression | Converts `3` to `DayOfWeek.Wednesday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 4)` | `DayOfWeek.Thursday` | Expression | Converts `4` to `DayOfWeek.Thursday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 5)` | `DayOfWeek.Friday` | Expression | Converts `5` to `DayOfWeek.Friday` value. See [Enum.ToObject][] | +| | `(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 6)` | `DayOfWeek.Saturday` | Expression | Converts `6` to `DayOfWeek.Saturday` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert DayOfWeek to Text + +The following table shows some of the ways that a `DayOfWeek` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `DayOfWeek.Sunday.ToString()` | `"Sunday"` | Expression | Converts `DayOfWeek.Sunday` to `"Sunday"`. See [Enum.ToString][] | +| | `DayOfWeek.Monday.ToString()` | `"Monday"` | Expression | Converts `DayOfWeek.Monday` to `"Monday"`. See [Enum.ToString][] | +| | `DayOfWeek.Tuesday.ToString()` | `"Tuesday"` | Expression | Converts `DayOfWeek.Tuesday` to `"Tuesday"`. See [Enum.ToString][] | +| | `DayOfWeek.Wednesday.ToString()` | `"Wednesday"` | Expression | Converts `DayOfWeek.Wednesday` to `"Wednesday"`. See [Enum.ToString][] | +| | `DayOfWeek.Thursday.ToString()` | `"Thursday"` | Expression | Converts `DayOfWeek.Thursday` to `"Thursday"`. See [Enum.ToString][] | +| | `DayOfWeek.Friday.ToString()` | `"Friday"` | Expression | Converts `DayOfWeek.Friday` to `"Friday"`. See [Enum.ToString][] | +| | `DayOfWeek.Saturday.ToString()` | `"Saturday"` | Expression | Converts `DayOfWeek.Saturday` to `"Saturday"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(DayOfWeek.Sunday)` | `"Sunday"` | Expression | Converts `DayOfWeek.Sunday` to `"Sunday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Monday)` | `"Monday"` | Expression | Converts `DayOfWeek.Monday` to `"Monday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Tuesday)` | `"Tuesday"` | Expression | Converts `DayOfWeek.Tuesday` to `"Tuesday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Wednesday)` | `"Wednesday"` | Expression | Converts `DayOfWeek.Wednesday` to `"Wednesday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Thursday)` | `"Thursday"` | Expression | Converts `DayOfWeek.Thursday` to `"Thursday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Friday)` | `"Friday"` | Expression | Converts `DayOfWeek.Friday` to `"Friday"`. See [Convert.ToString][] | +| | `Convert.ToString(DayOfWeek.Saturday)` | `"Saturday"` | Expression | Converts `DayOfWeek.Saturday` to `"Saturday"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `DayOfWeek.Sunday` | `"Sunday"` | N/A | Converts `DayOfWeek.Sunday` to `"Sunday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Monday` | `"Monday"` | N/A | Converts `DayOfWeek.Monday` to `"Monday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Tuesday` | `"Tuesday"` | N/A | Converts `DayOfWeek.Tuesday` to `"Tuesday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Wednesday` | `"Wednesday"` | N/A | Converts `DayOfWeek.Wednesday` to `"Wednesday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Thursday` | `"Thursday"` | N/A | Converts `DayOfWeek.Thursday` to `"Thursday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Friday` | `"Friday"` | N/A | Converts `DayOfWeek.Friday` to `"Friday"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `DayOfWeek.Saturday` | `"Saturday"` | N/A | Converts `DayOfWeek.Saturday` to `"Saturday"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `DayOfWeek.Sunday` | `"0"` | N/A | Converts `DayOfWeek.Sunday` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Monday` | `"1"` | N/A | Converts `DayOfWeek.Monday` to `"1"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Tuesday` | `"2"` | N/A | Converts `DayOfWeek.Tuesday` to `"2"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Wednesday` | `"3"` | N/A | Converts `DayOfWeek.Wednesday` to `"3"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Thursday` | `"4"` | N/A | Converts `DayOfWeek.Thursday` to `"4"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Friday` | `"5"` | N/A | Converts `DayOfWeek.Friday` to `"5"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `DayOfWeek.Saturday` | `"6"` | N/A | Converts `DayOfWeek.Saturday` to `"6"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert DayOfWeek to a Number + +The following table shows some of the ways that a `DayOfWeek` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)DayOfWeek.Sunday` | `0` | Expression | [Casts][Explicit Casting] `DayOfWeek.Sunday` to `0` | +| | `(Int32)DayOfWeek.Monday` | `1` | Expression | [Casts][Explicit Casting] `DayOfWeek.Monday` to `1` | +| | `(Int32)DayOfWeek.Tuesday` | `2` | Expression | [Casts][Explicit Casting] `DayOfWeek.Tuesday` to `2` | +| | `(Int32)DayOfWeek.Wednesday`| `3` | Expression | [Casts][Explicit Casting] `DayOfWeek.Wednesday` to `3` | +| | `(Int32)DayOfWeek.Thursday` | `4` | Expression | [Casts][Explicit Casting] `DayOfWeek.Thursday` to `4` | +| | `(Int32)DayOfWeek.Friday` | `5` | Expression | [Casts][Explicit Casting] `DayOfWeek.Friday` to `5` | +| | `(Int32)DayOfWeek.Saturday` | `6` | Expression | [Casts][Explicit Casting] `DayOfWeek.Saturday` to `6` | +| Use `Convert.ToInt32` | `Convert.ToInt32(DayOfWeek.Sunday)` | `0` | Expression | Converts `DayOfWeek.Sunday` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Monday)` | `1` | Expression | Converts `DayOfWeek.Monday` to `1`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Tuesday)` | `2` | Expression | Converts `DayOfWeek.Tuesday` to `2`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Wednesday)`| `3` | Expression | Converts `DayOfWeek.Wednesday` to `3`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Thursday)` | `4` | Expression | Converts `DayOfWeek.Thursday` to `4`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Friday)` | `5` | Expression | Converts `DayOfWeek.Friday` to `5`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(DayOfWeek.Saturday)` | `6` | Expression | Converts `DayOfWeek.Saturday` to `6`. See [Convert.ToInt32][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `DayOfWeek`. +* The Literal Editor is available for [Input][] properties where the data type is `DayOfWeek`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `DayOfWeek`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int32][] +* [String][] + +### Related Concepts + +* [Working with Enums][] +* [Explicit Casting][] + +### External Documentation + +* [System.DayOfWeek][] +* [System.Enum][] + +[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" >}} + +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[System.DayOfWeek]: {{< url path="MSDocs.DotNet.Api.System.DayOfWeek.MainDoc" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/timeperiod.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/timeperiod.md new file mode 100644 index 000000000..a2de619fd --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/timeperiod.md @@ -0,0 +1,60 @@ +--- +title: "TimePeriod" +linkTitle: "TimePeriod" +description: "Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of `years`, `months`, `days`, `hours`, `minutes`, `seconds`, and `milliseconds`." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.DateAndTime.TimePeriod)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `TimePeriod` datatype is used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of `years`, `months`, `days`, `hours`, `minutes`, `seconds`, and `milliseconds`. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `TimePeriod` | +| **Full Name:** | `Cortex.DataTypes.DateAndTime.TimePeriod` | +| **Alias:** | N/A | +| **Description:** | Used to represent a time interval that is measured as a positive or negative number of `years`, `months`, `days`, `hours`, `minutes`, `seconds`, and `milliseconds`. | +| **Default Value:** | `null` | +| **Can be used as:** | `TimePeriod`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TimePeriod`. +- The Literal Editor is available for [Input][] properties where the data type is `TimePeriod`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TimePeriod`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [TimeSpan] + +### Related Concepts + +- [Working with Date and Time][] + +### External Documentation + +None + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[TimeSpan]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimeSpan.MainDoc" >}} + +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/date-and-time/timespan.md b/content/en/docs/2024.9/Reference/data-types/date-and-time/timespan.md new file mode 100644 index 000000000..5c0d0abc6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/date-and-time/timespan.md @@ -0,0 +1,62 @@ +--- +title: "TimeSpan" +linkTitle: "TimeSpan" +description: "Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of `days`, `hours`, `minutes`, `seconds`, and `milliseconds`. It can be used wherever a `TimePeriod` is expected, and wll be converted to a `TimePeriod` automatically." +--- + +# {{% param title %}} + +

(System.TimeSpan)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of `days`, `hours`, `minutes`, `seconds`, and `milliseconds`. It can be used wherever a `TimePeriod` is expected, and wll be converted to a `TimePeriod` automatically. + +| | | +|-|-| +| **Category:** | Date & Time | +| **Name:** | `TimeSpan` | +| **Full Name:** | `System.TimeSpan` | +| **Alias:** | N/A | +| **Description:** | Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of `days`, `hours`, `minutes`, `seconds`, and `milliseconds`. It can be used wherever a `TimePeriod` is expected, and wll be converted to a `TimePeriod` automatically. | +| **Default Value:** | `new TimeSpan(0, 0, 0, 0, 0)` | +| **Can be used as:** | `TimeSpan`, `TimePeriod`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TimeSpan`. +- The Literal Editor is available for [Input][] properties where the data type is `TimeSpan`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TimeSpan`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [TimePeriod][] + +### Related Concepts + +- [Working with Date and Time][] + +### External Documentation + +- [System.TimeSpan][] + +[Working with Date and Time]: {{< url path="Cortex.Reference.Concepts.WorkingWith.DateAndTime.MainDoc" >}} + +[TimePeriod]: {{< url path="Cortex.Reference.DataTypes.DateAndTime.TimePeriod.MainDoc" >}} + +[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" >}} + +[System.TimeSpan]: {{< url path="MSDocs.DotNet.Api.System.TimeSpan.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/_index.md b/content/en/docs/2024.9/Reference/data-types/email/_index.md new file mode 100644 index 000000000..8e6244a23 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/_index.md @@ -0,0 +1,6 @@ +--- +title: "Email" +linkTitle: "Email" +description: "Data types used for working with emails and connecting to mail servers." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailCredentials.md b/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailCredentials.md new file mode 100644 index 000000000..6fc0e11da --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailCredentials.md @@ -0,0 +1,12 @@ +--- +title: "EmailCredentials" +linkTitle: "EmailCredentials" +description: "Used to represent details required to authenticate with a mail server." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.Authentication.EmailCredentials)

+ +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailUserCredentials.md b/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailUserCredentials.md new file mode 100644 index 000000000..28bdf04d9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/authentication/EmailUserCredentials.md @@ -0,0 +1,12 @@ +--- +title: "EmailUserCredentials" +linkTitle: "EmailUserCredentials" +description: "Used to represent details required to authenticate with a mail server." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.Authentication.EmailUserCredentials)

+ +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/authentication/IEmailCredentials.md b/content/en/docs/2024.9/Reference/data-types/email/authentication/IEmailCredentials.md new file mode 100644 index 000000000..308b27143 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/authentication/IEmailCredentials.md @@ -0,0 +1,12 @@ +--- +title: "IEmailCredentials" +linkTitle: "IEmailCredentials" +description: "Any data type used to represent details required to authenticate with a mail server." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.Authentication.IEmailCredentials)

+ +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/authentication/_index.md b/content/en/docs/2024.9/Reference/data-types/email/authentication/_index.md new file mode 100644 index 000000000..8a7eef1cf --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/authentication/_index.md @@ -0,0 +1,6 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Data types used for authenticating with mail servers." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/email/basicemailsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/email/basicemailsessiondetails.md new file mode 100644 index 000000000..0bcb0d90d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/basicemailsessiondetails.md @@ -0,0 +1,139 @@ +--- +title: "BasicEmailSessionDetails" +linkTitle: "BasicEmailSessionDetails" +description: "Used to represent configuration for opening and maintaining a session with a mail server." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.BasicEmailSessionDetails)

+ +## Summary + +The `BasicEmailSessionDetails` data type is used to represent configuration for opening and maintaining a session with a mail server. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `BasicEmailSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.Email.BasicEmailSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Configuration for opening and maintaining a session with a mail server. | +| **Default Value:** | null | +| **Can be used as:** | `BasicEmailSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ServerDetails + +The ServerDetails are used to configure the [Host][] and [Port][] of the mail server to connect to and whether or not to [UseSsl][]. + +| | | +|--------------------|---------------------------| +| Data Type | [ServerDetails][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [ServerDetails][] with value shown below: | + +```json +{ + "Host": "", + "Port": 465, + "UseSsl": true +} +``` + +### Credentials + +The Credentials are used to configure the [Username][] and [Password][] used for authentication. + +| | | +|--------------------|---------------------------| +| Data Type | [UserCredentials][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [UserCredentials][] with value shown below: | + +```json +{ + "Domain": "", + "Username": "", + "Password": "" +} +``` + +## Remarks + +### Create a BasicEmailSessionDetails + +The following table shows some of the ways that `BasicEmailSessionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `BasicEmailSessionDetails` constructor | `new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}` | Expression | The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the [Password][], see [EncryptedText][]. | + +A `BasicEmailSessionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `ServerDetails` | `ServerDetails` | Host: `"smtp.gmail.com"`
Port: `465`
UseSsl: `true` | The [ServerDetails][ServerDetails Property] that are used to connect to the server. | +| `Credentials` | `UserCredentials` | Domain: `""`
Username: `"sender@gmail.com"`
Password: `"encryptedPassword"` | The [Credentials][Credentials Property] that are used for authentication on the server.

The [Password][] property in the [UserCredentials][] must be encrypted, for more information on how to encrypt the [Password][], see [EncryptedText][].| + +### Convert BasicEmailSessionDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}` | `"{\r\n \"ServerDetails\": {\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n },\r\n \"Credentials\": {\r\n \"Domain\": null,\r\n \"Username\": \"sender@gmail.com\",\r\n \"Password\": \"encryptedPassword\"\r\n }\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `BasicEmailSessionDetails`. +- The Literal Editor is available for [Input][] properties where the data type is `BasicEmailSessionDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `BasicEmailSessionDetails`. + +### Known Limitations + +Currently, this data type is not compatible for use with unauthenticated mail servers. + +This limitation may be removed in the future. + +## See Also + +### Related Data Types + +- [ServerDetails][] +- [UserCredentials][] +- [EncryptedText][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[ServerDetails Property]: {{< ref "#serverdetails" >}} +[Credentials Property]: {{< ref "#credentials" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[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" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/emailaddress.md b/content/en/docs/2024.9/Reference/data-types/email/emailaddress.md new file mode 100644 index 000000000..8f7cad95c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/emailaddress.md @@ -0,0 +1,117 @@ +--- +title: "EmailAddress" +linkTitle: "EmailAddress" +description: "Used to represent an email address." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.EmailAddress)

+ +## Summary + +The `EmailAddress` data type is used to represent an email address. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `EmailAddress` | +| **Full Name:** | `Cortex.DataTypes.Email.EmailAddress` | +| **Alias:** | N/A | +| **Description:** | An email address. | +| **Default Value:** | `null` | +| **Can be used as:** | `EmailAddress`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Name + +Name is used to define the display name associated with the email address. + +This property is not required. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### Address + +Address is used to define the email address. This must be a valid email address as outlined in [RFC 5321][]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +## Remarks + +### Create an EmailAddress + +The following table shows some of the ways that an `EmailAddress` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `EmailAddress` constructor | `new EmailAddress(name: "Sender", address: "sender@outlook.com")`| `{"Name": "Sender", "Address": "sender@outlook.com"}` | Expression | Name specified | +| | `new EmailAddress(address: "sender@outlook.com")`| `{"Name": null, "Address": "sender@outlook.com"}` | Expression | Name not specified | + +An `EmailAddress` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Name` | `String` | `"Sender"` | [Name][Name Property] defines the display name associated with the email address. | +| `Address` | `String` | `"sender@outlook.com"` | [Address][Address Property] defines the email address. | + +### Convert EmailAddress to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Name": "Sender", "Address": "sender@outlook.com"}` | `"{\r\n \"Name\": \"Sender\",\r\n \"Address\": \"sender@outlook.com\"\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EmailAddress`. +- The Literal Editor is available for [Input][] properties where the data type is `EmailAddress`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EmailAddress`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EmailMessage][] +- [String][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +- [RFC 5321][] + +[Name Property]: {{< ref "#name" >}} +[Address Property]: {{< ref "#address" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[EmailMessage]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[RFC 5321]: {{< url path="IETF.Email.RFC5321" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/emailmessage.md b/content/en/docs/2024.9/Reference/data-types/email/emailmessage.md new file mode 100644 index 000000000..30479f19a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/emailmessage.md @@ -0,0 +1,228 @@ +--- +title: "EmailMessage" +linkTitle: "EmailMessage" +description: "Used to represent an email message." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.EmailMessage)

+ +## Summary + +The `EmailMessage` data type is used to represent an email message. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `EmailMessage` | +| **Full Name:** | `Cortex.DataTypes.Email.EmailMessage` | +| **Alias:** | N/A | +| **Description:** | An email message. | +| **Default Value:** | `null` | +| **Can be used as:** | `EmailMessage`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### To + +To is used to define the list of recipients for the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[EmailAddress][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[EmailAddress][]> with value `new List(){ new EmailAddress("") }` | + +### From + +From is used to define the sender of the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [EmailAddress][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [EmailAddress][] with value shown below: | + +```json +{ + "Name": "", + "Address": "" +} +``` + +### Cc + +Cc is used to define the list of [CC][CC Glossary] recipients for the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[EmailAddress][]> | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[EmailAddress][]> with value `null` | + +### Bcc + +Bcc is used to define the list of [BCC][BCC Glossary] recipients for the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[EmailAddress][]> | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[EmailAddress][]> with value `null` | + +### Priority + +Priority is used to define the priority of the email message, for more information on the range of values this can take, see [EmailMessagePriority][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EmailMessagePriority][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [EmailMessagePriority][] with value `EmailMessagePriority.Normal` | + +### Subject + +Subject is used to define the subject of the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### BodyFormat + +BodyFormat is used to define the format of the email body, for more information on the range of values this can take, see [EmailMessageBodyFormat][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EmailMessageBodyFormat][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [EmailMessageBodyFormat][] with value `EmailMessageBodyFormat.Text` | + +### Body + +The Body is used to define the body of the email message. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### Attachments + +The Attachments is used to define the list of attachments for the email message, where each item in the list is a path pointing to the attachment. + +The supported file path formats are dependent on the block being used: + +- [Send Email Using SMTP Server Block][Send Email Using SMTP Server Block Supported File Paths] +- [Send Email Using Gmail Block][Send Email Using Gmail Block Supported File Paths] + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with value `null` | + +## Remarks + +### Create an EmailMessage + +The following table shows some of the ways that an `EmailMessage` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `EmailMessage` constructor | `new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)` | `{"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": []}`| Expression | No [Advanced Properties][Advanced] properties configured | +| | `new EmailMessage(to: new List(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: new List(){ new EmailAddress("cc@outlook.com") }, bcc: new List(){ new EmailAddress("bcc@outlook.com") }, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Text, body: "Example email body", attachments: new List(){ @"C:\attachment.txt" })` | `{"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Text", "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]}`| Expression | All [Advanced Properties][Advanced] properties configured | + +An `EmailMessage` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `To` | `IList` | `new List(){ "recipient@outlook.com" }` | [To][To Property] defines a list of recipients for the email message. | +| `From` | `EmailAddress` | Name: `Sender`
Address: `sender@outlook.com` | [From][From Property] defines the sender of the email message. | +| `Cc` | `IList` | `new List(){ "cc@outlook.com" }` | [Cc][Cc Property] defines a list of [CC][CC Glossary] recipients for the email message. | +| `Bcc` | `IList` | `new List(){ "bcc@outlook.com" }` | [Bcc][Bcc Property] defines a list of [BCC][BCC Glossary] recipients for the email message. | +| `Priority` | `EmailMessagePriority` | `Normal` | [Priority][Priority Property] defines the priority of the email message. | +| `Subject` | `String` | `Example subject` | [Subject][Subject Property] defines the subject of the email message. | +| `BodyFormat` | `EmailMessageBodyFormat` | `Text` | [BodyFormat][BodyFormat Property] defines the format of the email message body. | +| `Body` | `String` | `$@"Example body"` | [Body][Body Property] defines the body of the email message. | +| `Attachments` | `IList` | `new List(){ @"C:\attachment.txt" }` | [Attachments][Attachments Property] defines the list of attachments for the email message. | + +### Convert EmailMessage to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Text", "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]}` | `"{\r\n \"To\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"recipient@outlook.com\"\r\n }\r\n ],\r\n \"From\": {\r\n \"Name\": null,\r\n \"Address\": \"sender@outlook.com\"\r\n },\r\n \"Cc\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"cc@outlook.com\"\r\n }\r\n ],\r\n \"Bcc\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"bcc@outlook.com\"\r\n }\r\n ],\r\n \"Priority\": 2,\r\n \"Subject\": \"Example email subject\",\r\n \"BodyFormat\": 0,\r\n \"Body\": \"Example email body\",\r\n \"Attachments\": [\r\n \"C:\\attachment.txt\"\r\n ]\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EmailMessage`. +- The Literal Editor is available for [Input][] properties where the data type is `EmailMessage`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EmailMessage`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EmailAddress][] +- [EmailMessageBodyFormat][] +- [EmailMessagePriority][] +- [IList<TItem>][IList] +- [String][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[To Property]: {{< ref "#to" >}} +[From Property]: {{< ref "#from" >}} +[Cc Property]: {{< ref "#cc" >}} +[Bcc Property]: {{< ref "#bcc" >}} +[Priority Property]: {{< ref "#priority" >}} +[Subject Property]: {{< ref "#subject" >}} +[BodyFormat Property]: {{< ref "#bodyformat" >}} +[Body Property]: {{< ref "#body" >}} +[Attachments Property]: {{< ref "#attachments" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[EmailAddress]: {{< url path="Cortex.Reference.DataTypes.Email.EmailAddress.MainDoc" >}} +[EmailMessagePriority]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessagePriority.MainDoc" >}} +[EmailMessageBodyFormat]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessageBodyFormat.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[Send Email Using SMTP Server Block Supported File Paths]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.SupportedFilePaths" >}} +[Send Email Using Gmail Block Supported File Paths]: {{< url path="Cortex.Reference.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmail.SupportedFilePaths" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[BCC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.BCC" >}} +[CC Glossary]: {{< url path="Cortex.Reference.Glossary.A-E.CC" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/emailmessagebodyformat.md b/content/en/docs/2024.9/Reference/data-types/email/emailmessagebodyformat.md new file mode 100644 index 000000000..20171fec4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/emailmessagebodyformat.md @@ -0,0 +1,150 @@ +--- +title: "EmailMessageBodyFormat" +linkTitle: "EmailMessageBodyFormat" +description: "Used to represent the format of an email message body." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.EmailMessageBodyFormat)

+ +## Summary + +The `EmailMessageBodyFormat` data type is used to represent the format of an email message body. + +`EmailMessageBodyFormat` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `EmailMessageBodyFormat` | +| **Full Name:** | `Cortex.DataTypes.Email.EmailMessageBodyFormat` | +| **Alias:** | N/A | +| **Description:** | Format of an email message body. | +| **Size:** | `4` bytes | +| **Default Value:** | `EmailMessageBodyFormat.Text` | +| **Can be used as:** | `EmailMessageBodyFormat`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)EmailMessageBodyFormat.Text` or `(System.Int16)EmailMessageBodyFormat.Text` or `(short)EmailMessageBodyFormat.Text`) | +| | `Int32` (e.g. `(Int32)EmailMessageBodyFormat.Text` or `(System.Int32)EmailMessageBodyFormat.Text` or `(int)EmailMessageBodyFormat.Text`) | +| | `Int64` (e.g. `(Int64)EmailMessageBodyFormat.Text` or `(System.Int64)EmailMessageBodyFormat.Text` or `(long)EmailMessageBodyFormat.Text`) | +| | `Single` (e.g. `(Single)EmailMessageBodyFormat.Text` or `(System.Single)EmailMessageBodyFormat.Text` or `(float)EmailMessageBodyFormat.Text`) | +| | `Double` (e.g. `(Double)EmailMessageBodyFormat.Text` or `(System.Double)EmailMessageBodyFormat.Text` or `(double)EmailMessageBodyFormat.Text`) | + +## Values + +### Text + +| | | +|-|-| +| **Name:** | Text | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Used when an email message body format is plain text. | + +### Html + +| | | +|-|-| +| **Name:** | Html | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Used when an email message body format is HTML. | + +## Remarks + +### Create an EmailMessageBodyFormat + +The following table shows some of the ways that `EmailMessageBodyFormat` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare an `EmailMessageBodyFormat` literal | `Text` | `EmailMessageBodyFormat.Text`| Literal | Indicates Text | +| | `Html` | `EmailMessageBodyFormat.Html`| Literal | Indicates Html | +| Use an `EmailMessageBodyFormat` expression | `EmailMessageBodyFormat.Text` | `EmailMessageBodyFormat.Text`| Expression | Indicates Text | +| | `EmailMessageBodyFormat.Html` | `EmailMessageBodyFormat.Html`| Expression | Indicates Html | +| Use [Explicit Casting][] | `(EmailMessageBodyFormat)0` | `EmailMessageBodyFormat.Text` | Expression | Indicates Text | +| | `(EmailMessageBodyFormat)1` | `EmailMessageBodyFormat.Html` | Expression | Indicates Html | +| Use `Enum.Parse` | `(EmailMessageBodyFormat)Enum.Parse(typeof(EmailMessageBodyFormat), "Text")` | `EmailMessageBodyFormat.Text` | Expression | Parses `"Text"` and converts it to `EmailMessageBodyFormat.Text`. See [Enum.Parse][] | +| | `(EmailMessageBodyFormat)Enum.Parse(typeof(EmailMessageBodyFormat), "Html")` | `EmailMessageBodyFormat.Html` | Expression | Parses `"Html"` and converts it to `EmailMessageBodyFormat.Html`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(EmailMessageBodyFormat)Enum.ToObject(typeof(EmailMessageBodyFormat), 0)` | `EmailMessageBodyFormat.Text` | Expression | Converts `0` to `EmailMessageBodyFormat.Text` value. See [Enum.ToObject][] | +| | `(EmailMessageBodyFormat)Enum.ToObject(typeof(EmailMessageBodyFormat), 1)` | `EmailMessageBodyFormat.Html` | Expression | Converts `1` to `EmailMessageBodyFormat.Html` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert EmailMessageBodyFormat to Text + +The following table shows some of the ways that a `EmailMessageBodyFormat` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `EmailMessageBodyFormat.Text.ToString()` | `"Text"` | Expression | Converts `EmailMessageBodyFormat.Text` to `"Text"`. See [Enum.ToString][] | +| | `EmailMessageBodyFormat.Html.ToString()` | `"Html"` | Expression | Converts `EmailMessageBodyFormat.Html` to `"Html"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(EmailMessageBodyFormat.Text)` | `"Text"` | Expression | Converts `EmailMessageBodyFormat.Text` to `"Text"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailMessageBodyFormat.Html)` | `"Html"` | Expression | Converts `EmailMessageBodyFormat.Html` to `"Html"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `EmailMessageBodyFormat.Text` | `"Text"` | N/A | Converts `EmailMessageBodyFormat.Text` to `"Text"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailMessageBodyFormat.Html` | `"Html"` | N/A | Converts `EmailMessageBodyFormat.Html` to `"Html"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `EmailMessageBodyFormat.Text` | `"0"` | N/A | Converts `EmailMessageBodyFormat.Text` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailMessageBodyFormat.Html` | `"1"` | N/A | Converts `EmailMessageBodyFormat.Html` to `"1"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert EmailMessageBodyFormat to a Number + +The following table shows some of the ways that a `EmailMessageBodyFormat` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)EmailMessageBodyFormat.Text` | `0` | Expression | [Casts][Explicit Casting] `EmailMessageBodyFormat.Text` to `0` | +| | `(Int32)EmailMessageBodyFormat.Html` | `1` | Expression | [Casts][Explicit Casting] `EmailMessageBodyFormat.Html` to `1` | +| Use `Convert.ToInt32` | `Convert.ToInt32(EmailMessageBodyFormat.Text)` | `0` | Expression | Converts `EmailMessageBodyFormat.Text` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailMessageBodyFormat.Html)` | `1` | Expression | Converts `EmailMessageBodyFormat.Html` to `1`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EmailMessageBodyFormat`. +- The Literal Editor is available for [Input][] properties where the data type is `EmailMessageBodyFormat`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EmailMessageBodyFormat`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EmailMessage][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Email][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[EmailMessage]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.MainDoc" >}} +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/emailmessagepriority.md b/content/en/docs/2024.9/Reference/data-types/email/emailmessagepriority.md new file mode 100644 index 000000000..765780d30 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/emailmessagepriority.md @@ -0,0 +1,169 @@ +--- +title: "EmailMessagePriority" +linkTitle: "EmailMessagePriority" +description: "Used to represent the priority of an email message." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.EmailMessagePriority)

+ +## Summary + +The `EmailMessagePriority` data type is used to represent the priority of an email message. + +`EmailMessagePriority` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `EmailMessagePriority` | +| **Full Name:** | `Cortex.DataTypes.Email.EmailMessagePriority` | +| **Alias:** | N/A | +| **Description:** | Priority of an email message. | +| **Size:** | `4` bytes | +| **Default Value:** | `EmailMessagePriority.Normal` | +| **Can be used as:** | `EmailMessagePriority`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)EmailMessagePriority.Normal` or `(System.Int16)EmailMessagePriority.Normal` or `(short)EmailMessagePriority.Normal`) | +| | `Int32` (e.g. `(Int32)EmailMessagePriority.Normal` or `(System.Int32)EmailMessagePriority.Normal` or `(int)EmailMessagePriority.Normal`) | +| | `Int64` (e.g. `(Int64)EmailMessagePriority.Normal` or `(System.Int64)EmailMessagePriority.Normal` or `(long)EmailMessagePriority.Normal`) | +| | `Single` (e.g. `(Single)EmailMessagePriority.Normal` or `(System.Single)EmailMessagePriority.Normal` or `(float)EmailMessagePriority.Normal`) | +| | `Double` (e.g. `(Double)EmailMessagePriority.Normal` or `(System.Double)EmailMessagePriority.Normal` or `(double)EmailMessagePriority.Normal`) | + +## Values + +### Normal + +| | | +|-|-| +| **Name:** | Normal | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Used when an email is marked with normal priority. | + +### NonUrgent + +| | | +|-|-| +| **Name:** | NonUrgent | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Used when an email is marked with non-urgent priority. | + +### Urgent + +| | | +|-|-| +| **Name:** | Urgent | +| **Value:** | [Int32][] with value `2` | +| **Notes:** | Used when an email is marked with urgent priority. | + +## Remarks + +### Create an EmailMessagePriority + +The following table shows some of the ways that `EmailMessagePriority` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare an `EmailMessagePriority` literal | `Normal` | `EmailMessagePriority.Normal`| Literal | Indicates Normal | +| | `NonUrgent` | `EmailMessagePriority.NonUrgent`| Literal | Indicates NonUrgent | +| | `Urgent` | `EmailMessagePriority.Urgent`| Literal | Indicates Urgent | +| Use an `EmailMessagePriority` expression | `EmailMessagePriority.Normal` | `EmailMessagePriority.Normal`| Expression | Indicates Normal | +| | `EmailMessagePriority.NonUrgent` | `EmailMessagePriority.NonUrgent`| Expression | Indicates NonUrgent | +| | `EmailMessagePriority.Urgent` | `EmailMessagePriority.Urgent`| Expression | Indicates Urgent | +| Use [Explicit Casting][] | `(EmailMessagePriority)0` | `EmailMessagePriority.Normal` | Expression | Indicates Normal | +| | `(EmailMessagePriority)1` | `EmailMessagePriority.NonUrgent` | Expression | Indicates NonUrgent | +| | `(EmailMessagePriority)2` | `EmailMessagePriority.Urgent` | Expression | Indicates Urgent | +| Use `Enum.Parse` | `(EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "Normal")` | `EmailMessagePriority.Normal` | Expression | Parses `"Normal"` and converts it to `EmailMessagePriority.Normal`. See [Enum.Parse][] | +| | `(EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "NonUrgent")` | `EmailMessagePriority.NonUrgent` | Expression | Parses `"NonUrgent"` and converts it to `EmailMessagePriority.NonUrgent`. See [Enum.Parse][] | +| | `(EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "Urgent")` | `EmailMessagePriority.Urgent` | Expression | Parses `"Urgent"` and converts it to `EmailMessagePriority.Urgent`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 0)` | `EmailMessagePriority.Normal` | Expression | Converts `0` to `EmailMessagePriority.Normal` value. See [Enum.ToObject][] | +| | `(EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 1)` | `EmailMessagePriority.NonUrgent` | Expression | Converts `1` to `EmailMessagePriority.NonUrgent` value. See [Enum.ToObject][] | +| | `(EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 2)` | `EmailMessagePriority.Urgent` | Expression | Converts `2` to `EmailMessagePriority.Urgent` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert EmailMessagePriority to Text + +The following table shows some of the ways that a `EmailMessagePriority` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `EmailMessagePriority.Normal.ToString()` | `"Normal"` | Expression | Converts `EmailMessagePriority.Normal` to `"Normal"`. See [Enum.ToString][] | +| | `EmailMessagePriority.NonUrgent.ToString()` | `"NonUrgent"` | Expression | Converts `EmailMessagePriority.NonUrgent` to `"NonUrgent"`. See [Enum.ToString][] | +| | `EmailMessagePriority.Urgent.ToString()` | `"Urgent"` | Expression | Converts `EmailMessagePriority.Urgent` to `"Urgent"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(EmailMessagePriority.Normal)` | `"Normal"` | Expression | Converts `EmailMessagePriority.Normal` to `"Normal"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailMessagePriority.NonUrgent)` | `"NonUrgent"` | Expression | Converts `EmailMessagePriority.NonUrgent` to `"NonUrgent"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailMessagePriority.Urgent)` | `"Urgent"` | Expression | Converts `EmailMessagePriority.Urgent` to `"Urgent"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `EmailMessagePriority.Normal` | `"Normal"` | N/A | Converts `EmailMessagePriority.Normal` to `"Normal"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailMessagePriority.NonUrgent` | `"NonUrgent"` | N/A | Converts `EmailMessagePriority.NonUrgent` to `"NonUrgent"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailMessagePriority.Urgent` | `"Urgent"` | N/A | Converts `EmailMessagePriority.Urgent` to `"Urgent"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `EmailMessagePriority.Normal` | `"0"` | N/A | Converts `EmailMessagePriority.Normal` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailMessagePriority.NonUrgent` | `"1"` | N/A | Converts `EmailMessagePriority.NonUrgent` to `"1"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailMessagePriority.Urgent` | `"2"` | N/A | Converts `EmailMessagePriority.Urgent` to `"2"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert EmailMessagePriority to a Number + +The following table shows some of the ways that a `EmailMessagePriority` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)EmailMessagePriority.Normal` | `0` | Expression | [Casts][Explicit Casting] `EmailMessagePriority.Normal` to `0` | +| | `(Int32)EmailMessagePriority.NonUrgent` | `1` | Expression | [Casts][Explicit Casting] `EmailMessagePriority.NonUrgent` to `1` | +| | `(Int32)EmailMessagePriority.Urgent` | `2` | Expression | [Casts][Explicit Casting] `EmailMessagePriority.Urgent` to `2` | +| Use `Convert.ToInt32` | `Convert.ToInt32(EmailMessagePriority.Normal)` | `0` | Expression | Converts `EmailMessagePriority.Normal` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailMessagePriority.NonUrgent)` | `1` | Expression | Converts `EmailMessagePriority.NonUrgent` to `1`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailMessagePriority.Urgent)` | `2` | Expression | Converts `EmailMessagePriority.Urgent` to `2`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EmailMessagePriority`. +- The Literal Editor is available for [Input][] properties where the data type is `EmailMessagePriority`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EmailMessagePriority`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EmailMessage][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Email][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[EmailMessage]: {{< url path="Cortex.Reference.DataTypes.Email.EmailMessage.MainDoc" >}} +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/email/emailsessionerrorcode.md b/content/en/docs/2024.9/Reference/data-types/email/emailsessionerrorcode.md new file mode 100644 index 000000000..4e0fa35d4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/email/emailsessionerrorcode.md @@ -0,0 +1,265 @@ +--- +title: "EmailSessionErrorCode" +linkTitle: "EmailSessionErrorCode" +description: "Used to represent an error code explaining the reason an `EmailSessionException` occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Email.EmailSessionErrorCode)

+ +## Summary + +The `EmailSessionErrorCode` data type is used to represent an error code explaining the reason an [EmailSessionException][] occurred. For more information on the exception itself, see [EmailSessionException][]. + +`EmailSessionErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Email | +| **Name:** | `EmailSessionErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Email.EmailSessionErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason an [EmailSessionException][] occurred. | +| **Size:** | `4` bytes | +| **Default Value:** | `(EmailSessionErrorCode)0` | +| **Can be used as:** | `EmailSessionErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)EmailSessionErrorCode.InvalidPort` or `(System.Int16)EmailSessionErrorCode.InvalidPort` or `(short)EmailSessionErrorCode.InvalidPort`) | +| | `Int32` (e.g. `(Int32)EmailSessionErrorCode.InvalidPort` or `(System.Int32)EmailSessionErrorCode.InvalidPort` or `(int)EmailSessionErrorCode.InvalidPort`) | +| | `Int64` (e.g. `(Int64)EmailSessionErrorCode.InvalidPort` or `(System.Int64)EmailSessionErrorCode.InvalidPort` or `(long)EmailSessionErrorCode.InvalidPort`) | +| | `Single` (e.g. `(Single)EmailSessionErrorCode.InvalidPort` or `(System.Single)EmailSessionErrorCode.InvalidPort` or `(float)EmailSessionErrorCode.InvalidPort`) | +| | `Double` (e.g. `(Double)EmailSessionErrorCode.InvalidPort` or `(System.Double)EmailSessionErrorCode.InvalidPort` or `(double)EmailSessionErrorCode.InvalidPort`) | + +## Values + +### InvalidPort + +| | | +|-|-| +| **Name:** | InvalidPort | +| **Value:** | [Int32][] with value `100` | +| **Notes:** | Used when an [EmailSessionException][] occured due to an invalid [Port][] being provided in [ServerDetails][]. See [Invalid Port][InvalidPort]. | + +### InvalidHost + +| | | +|-|-| +| **Name:** | InvalidHost | +| **Value:** | [Int32][] with value `101` | +| **Notes:** | Used when an [EmailSessionException][] occured due to an invalid [Host][] being provided in [ServerDetails][]. See [Invalid Host][InvalidHost]. | + +### SslRequired + +| | | +|-|-| +| **Name:** | SslRequired | +| **Value:** | [Int32][] with value `200` | +| **Notes:** | Used when an [EmailSessionException][] occured due to [UseSsl][] being set to `false` in [ServerDetails][] when trying to establish a connection on a [Port][] which requires [SSL][]. See [SSL Required][SslRequired]. | + +### SslUnsupported + +| | | +|-|-| +| **Name:** | SslUnsupported | +| **Value:** | [Int32][] with value `201` | +| **Notes:** | Used when an [EmailSessionException][] occured due to [UseSsl][] being set to `true` in [ServerDetails][] when trying to establish a connection on a [Port][] which does not support [SSL][]. See [SSL Unsupported][SslUnsupported Exception].| + +### InvalidUserCredentials + +| | | +|-|-| +| **Name:** | InvalidUserCredentials | +| **Value:** | [Int32][] with value `300` | +| **Notes:** | Used when an [EmailSessionException][] occured due to an invalid [Username][] and [Password][] combination being provided in [UserCredentials][]. See [Invalid User Credentials][InvalidUserCredentials]. | + +### InvalidCertificate + +| | | +|-|-| +| **Name:** | InvalidCertificate | +| **Value:** | [Int32][] with value `400` | +| **Notes:** | Used when an [EmailSessionException][] occured due to an invalid [CertificatePath][] and [CertificatePassword][] combination being provided in [GmailOAuthCertificateCredentials][]. See [Invalid SSL Certificate][InvalidSslCertificate]. | + +### InvalidGmailClientCredentials + +| | | +|-|-| +| **Name:** | InvalidGmailClientCredentials | +| **Value:** | [Int32][] with value `401` | +| **Notes:** | Used when an [EmailSessionException][] occured due to an invalid [FromAddress][] and [ClientId][] combination being provided in [GmailOAuthCertificateCredentials][]. See [Invalid Gmail Client Credentials][InvalidClientCredentials]. | + +## Remarks + +### Create an EmailSessionErrorCode + +The following table shows some of the ways that `EmailSessionErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `EmailSessionErrorCode` expression | `EmailSessionErrorCode.InvalidPort` | `EmailSessionErrorCode.InvalidPort`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Port][] being provided in [ServerDetails][] | +| | `EmailSessionErrorCode.InvalidHost` | `EmailSessionErrorCode.InvalidHost`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Host][] being provided in [ServerDetails][] | +| | `EmailSessionErrorCode.SslRequired` | `EmailSessionErrorCode.SslRequired`| Expression | Indicates an [EmailSessionException][] occured due to [UseSsl][] being set to `false` in [ServerDetails][] when trying to establish a connection on a [Port][] which requires [SSL][] | +| | `EmailSessionErrorCode.SslUnsupported` | `EmailSessionErrorCode.SslUnsupported`| Expression | Indicates an [EmailSessionException][] occured due to [UseSsl][] being set to `true` in [ServerDetails][] when trying to establish a connection on a [Port][] which does not support [SSL][] | +| | `EmailSessionErrorCode.InvalidUserCredentials` | `EmailSessionErrorCode.InvalidUserCredentials`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Username][] and [Password][] combination being provided in [UserCredentials][] | +| | `EmailSessionErrorCode.InvalidCertificate` | `EmailSessionErrorCode.InvalidCertificate`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [CertificatePath][] and [CertificatePassword][] combination being provided in [GmailOAuthCertificateCredentials][] | +| | `EmailSessionErrorCode.InvalidGmailClientCredentials` | `EmailSessionErrorCode.InvalidGmailClientCredentials`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [FromAddress][] and [ClientId][] combination being provided in [GmailOAuthCertificateCredentials][] | +| Use [Explicit Casting][] | `(EmailSessionErrorCode)100` | `EmailSessionErrorCode.InvalidPort`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Port][] being provided in [ServerDetails][] | +| | `(EmailSessionErrorCode)101` | `EmailSessionErrorCode.InvalidHost`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Host][] being provided in [ServerDetails][] | +| | `(EmailSessionErrorCode)200` | `EmailSessionErrorCode.SslRequired`| Expression | Indicates an [EmailSessionException][] occured due to [UseSsl][] being set to `false` in [ServerDetails][] when trying to establish a connection on a [Port][] which requires [SSL][] | +| | `(EmailSessionErrorCode)201` | `EmailSessionErrorCode.SslUnsupported`| Expression | Indicates an [EmailSessionException][] occured due to [UseSsl][] being set to `true` in [ServerDetails][] when trying to establish a connection on a [Port][] which does not support [SSL][] | +| | `(EmailSessionErrorCode)300` | `EmailSessionErrorCode.InvalidUserCredentials`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [Username][] and [Password][] combination being provided in [UserCredentials][] | +| | `(EmailSessionErrorCode)400` | `EmailSessionErrorCode.InvalidCertificate`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [CertificatePath][] and [CertificatePassword][] combination being provided in [GmailOAuthCertificateCredentials][] | +| | `(EmailSessionErrorCode)401` | `EmailSessionErrorCode.InvalidGmailClientCredentials`| Expression | Indicates an [EmailSessionException][] occured due to an invalid [FromAddress][] and [ClientId][] combination being provided in [GmailOAuthCertificateCredentials][] | +| Use `Enum.Parse` | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidPort")` | `EmailSessionErrorCode.InvalidPort`| Expression | Parses `"InvalidPort"` and converts it to `EmailSessionErrorCode.InvalidPort`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidHost")` | `EmailSessionErrorCode.InvalidHost`| Expression | Parses `"InvalidHost"` and converts it to `EmailSessionErrorCode.InvalidHost`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "SslRequired")` | `EmailSessionErrorCode.SslRequired`| Expression | Parses `"SslRequired"` and converts it to `EmailSessionErrorCode.SslRequired`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "SslUnsupported")` | `EmailSessionErrorCode.SslUnsupported`| Expression | Parses `"SslUnsupported"` and converts it to `EmailSessionErrorCode.SslUnsupported`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidUserCredentials")` | `EmailSessionErrorCode.InvalidUserCredentials`| Expression | Parses `"InvalidUserCredentials"` and converts it to `EmailSessionErrorCode.InvalidUserCredentials`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidCertificate")` | `EmailSessionErrorCode.InvalidCertificate`| Expression | Parses `"InvalidCertificate"` and converts it to `EmailSessionErrorCode.InvalidCertificate`. See [Enum.Parse][] | +| | `(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidGmailClientCredentials")` | `EmailSessionErrorCode.InvalidGmailClientCredentials`| Expression | Parses `"InvalidGmailClientCredentials"` and converts it to `EmailSessionErrorCode.InvalidGmailClientCredentials`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 100)` | `EmailSessionErrorCode.InvalidPort`| Expression | Converts `100` to `EmailSessionErrorCode.InvalidPort` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 101)` | `EmailSessionErrorCode.InvalidHost`| Expression | Converts `101` to `EmailSessionErrorCode.InvalidHost` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 200)` | `EmailSessionErrorCode.SslRequired`| Expression | Converts `200` to `EmailSessionErrorCode.SslRequired` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 201)` | `EmailSessionErrorCode.SslUnsupported`| Expression | Converts `201` to `EmailSessionErrorCode.SslUnsupported` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 300)` | `EmailSessionErrorCode.InvalidUserCredentials`| Expression | Converts `300` to `EmailSessionErrorCode.InvalidUserCredentials` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 400)` | `EmailSessionErrorCode.InvalidCertificate`| Expression | Converts `400` to `EmailSessionErrorCode.InvalidCertificate` value. See [Enum.ToObject][] | +| | `(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 401)` | `EmailSessionErrorCode.InvalidGmailClientCredentials`| Expression | Converts `401` to `EmailSessionErrorCode.InvalidGmailClientCredentials` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert EmailSessionErrorCode to Text + +The following table shows some of the ways that an `EmailSessionErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `EmailSessionErrorCode.InvalidPort.ToString()` | `"InvalidPort"` | Expression | Converts `EmailSessionErrorCode.InvalidPort` to `"InvalidPort"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.InvalidHost.ToString()` | `"InvalidHost"` | Expression | Converts `EmailSessionErrorCode.InvalidHost` to `"InvalidHost"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.SslRequired.ToString()` | `"SslRequired"` | Expression | Converts `EmailSessionErrorCode.SslRequired` to `"SslRequired"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.SslUnsupported.ToString()` | `"SslUnsupported"` | Expression | Converts `EmailSessionErrorCode.SslUnsupported` to `"SslUnsupported"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.InvalidUserCredentials.ToString()` | `"InvalidUserCredentials"` | Expression | Converts `EmailSessionErrorCode.InvalidUserCredentials` to `"InvalidUserCredentials"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.InvalidCertificate.ToString()` | `"InvalidCertificate"` | Expression | Converts `EmailSessionErrorCode.InvalidCertificate` to `"InvalidCertificate"`. See [Enum.ToString][] | +| | `EmailSessionErrorCode.InvalidGmailClientCredentials.ToString()` | `"InvalidGmailClientCredentials"` | Expression | Converts `EmailSessionErrorCode.InvalidGmailClientCredentials` to `"InvalidGmailClientCredentials"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(EmailSessionErrorCode.InvalidPort)` | `"InvalidPort"` | Expression | Converts `EmailSessionErrorCode.InvalidPort` to `"InvalidPort"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.InvalidHost)` | `"InvalidHost"` | Expression | Converts `EmailSessionErrorCode.InvalidHost` to `"InvalidHost"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.SslRequired)` | `"SslRequired"` | Expression | Converts `EmailSessionErrorCode.SslRequired` to `"SslRequired"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.SslUnsupported)` | `"SslUnsupported"` | Expression | Converts `EmailSessionErrorCode.SslUnsupported` to `"SslUnsupported"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.InvalidUserCredentials)` | `"InvalidUserCredentials"` | Expression | Converts `EmailSessionErrorCode.InvalidUserCredentials` to `"InvalidUserCredentials"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.InvalidCertificate)` | `"InvalidCertificate"` | Expression | Converts `EmailSessionErrorCode.InvalidCertificate` to `"InvalidCertificate"`. See [Convert.ToString][] | +| | `Convert.ToString(EmailSessionErrorCode.InvalidGmailClientCredentials)` | `"InvalidGmailClientCredentials"` | Expression | Converts `EmailSessionErrorCode.InvalidGmailClientCredentials` to `"InvalidGmailClientCredentials"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `EmailSessionErrorCode.InvalidPort` | `"InvalidPort"` | N/A | Converts `EmailSessionErrorCode.InvalidPort` to `"InvalidPort"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidHost` | `"InvalidHost"` | N/A | Converts `EmailSessionErrorCode.InvalidHost` to `"InvalidHost"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.SslRequired` | `"SslRequired"` | N/A | Converts `EmailSessionErrorCode.SslRequired` to `"SslRequired"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.SslUnsupported` | `"SslUnsupported"` | N/A | Converts `EmailSessionErrorCode.SslUnsupported` to `"SslUnsupported"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidUserCredentials` | `"InvalidUserCredentials"` | N/A | Converts `EmailSessionErrorCode.InvalidUserCredentials` to `"InvalidUserCredentials"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidCertificate` | `"InvalidCertificate"` | N/A | Converts `EmailSessionErrorCode.InvalidCertificate` to `"InvalidCertificate"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidGmailClientCredentials` | `"InvalidGmailClientCredentials"` | N/A | Converts `EmailSessionErrorCode.InvalidGmailClientCredentials` to `"InvalidGmailClientCredentials"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `EmailSessionErrorCode.InvalidPort` | `"100"` | N/A | Converts `EmailSessionErrorCode.InvalidPort` to `"100"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidHost` | `"101"` | N/A | Converts `EmailSessionErrorCode.InvalidHost` to `"101"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.SslRequired` | `"200"` | N/A | Converts `EmailSessionErrorCode.SslRequired` to `"200"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.SslUnsupported` | `"201"` | N/A | Converts `EmailSessionErrorCode.SslUnsupported` to `"201"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidUserCredentials` | `"300"` | N/A | Converts `EmailSessionErrorCode.InvalidUserCredentials` to `"300"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidCertificate` | `"400"` | N/A | Converts `EmailSessionErrorCode.InvalidCertificate` to `"400"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `EmailSessionErrorCode.InvalidGmailClientCredentials` | `"401"` | N/A | Converts `EmailSessionErrorCode.InvalidGmailClientCredentials` to `"401"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert EmailSessionErrorCode to a Number + +The following table shows some of the ways that an `EmailSessionErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)EmailSessionErrorCode.InvalidPort` | `100` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.InvalidPort` to `100` | +| | `(Int32)EmailSessionErrorCode.InvalidHost` | `101` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.InvalidHost` to `101` | +| | `(Int32)EmailSessionErrorCode.SslRequired` | `200` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.SslRequired` to `200` | +| | `(Int32)EmailSessionErrorCode.SslUnsupported` | `201` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.SslUnsupported` to `201` | +| | `(Int32)EmailSessionErrorCode.InvalidUserCredentials` | `300` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.InvalidUserCredentials` to `300` | +| | `(Int32)EmailSessionErrorCode.InvalidCertificate` | `400` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.InvalidCertificate` to `400` | +| | `(Int32)EmailSessionErrorCode.InvalidGmailClientCredentials` | `401` | Expression | [Casts][Explicit Casting] `EmailSessionErrorCode.InvalidGmailClientCredentials` to `401` | +| Use `Convert.ToInt32` | `Convert.ToInt32(EmailSessionErrorCode.InvalidPort)` | `100` | Expression | Converts `EmailSessionErrorCode.InvalidPort` to `100`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.InvalidHost)` | `101` | Expression | Converts `EmailSessionErrorCode.InvalidHost` to `101`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.SslRequired)` | `200` | Expression | Converts `EmailSessionErrorCode.SslRequired` to `200`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.SslUnsupported)` | `201` | Expression | Converts `EmailSessionErrorCode.SslUnsupported` to `201`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.InvalidUserCredentials)` | `300` | Expression | Converts `EmailSessionErrorCode.InvalidUserCredentials` to `300`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.InvalidCertificate)` | `400` | Expression | Converts `EmailSessionErrorCode.InvalidCertificate` to `400`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(EmailSessionErrorCode.InvalidGmailClientCredentials)` | `401` | Expression | Converts `EmailSessionErrorCode.InvalidGmailClientCredentials` to `401`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EmailSessionErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `EmailSessionErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EmailSessionErrorCode`. + +### Known Limitations + +Currently for the [SslUnsupported][] error code, there are numerous reasons for why the exception may have occurred. For more information, see [SSL Unsupported][SslUnsupported Exception]. + +In the future this may change. + +## See Also + +### Related Data Types + +- [EmailSessionException][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Email][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[SslUnsupported]: {{< ref "#sslunsupported">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[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" >}} +[Username]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Username" >}} +[Password]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.Password" >}} + +[EmailSessionException]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.MainDoc" >}} +[InvalidPort]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidPort" >}} +[InvalidHost]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidHost" >}} +[SslRequired]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslRequired" >}} +[SslUnsupported Exception]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.SslUnsupported" >}} +[InvalidUserCredentials]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidUserCredentials" >}} +[InvalidSslCertificate]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidSslCertificate" >}} +[InvalidClientCredentials]: {{< url path="Cortex.Reference.Exceptions.Email.EmailSessionException.InvalidClientCredentials" >}} + +[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" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[SSL]: {{< url path="Cortex.Reference.Glossary.P-T.SSL" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/exceptions/_index.md b/content/en/docs/2024.9/Reference/data-types/exceptions/_index.md new file mode 100644 index 000000000..300adeba7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/exceptions/_index.md @@ -0,0 +1,6 @@ +--- +title: "Exceptions" +linkTitle: "Exceptions" +description: "Data types used for working with exceptions." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/exceptions/exception.md b/content/en/docs/2024.9/Reference/data-types/exceptions/exception.md new file mode 100644 index 000000000..d441b009e --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/exceptions/exception.md @@ -0,0 +1,60 @@ +--- +title: "Exception" +linkTitle: "Exception" +description: "Any data type used to represent an exception." +--- + +# {{% param title %}} + +

(System.Exception)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent an exception. + +| | | +|-|-| +| **Category:** | Exception | +| **Name:** | `Exception` | +| **Full Name:** | `System.Exception` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent an exception. | +| **Default Value:** | `null` | +| **Can be used as:** | `Exception`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Exception`. +- The Literal Editor is available for [Input][] properties where the data type is `Exception`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Exception`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +None + +### Related Concepts + +- [Exceptions][] + +### External Documentation + +- [System.Exception] + +[Exceptions]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Exceptions.MainDoc" >}} + +[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" >}} + +[System.Exception]: {{< url path="MSDocs.DotNet.Api.System.Exception" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/FileSystemInformation.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/FileSystemInformation.md new file mode 100644 index 000000000..b4e8702b4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/FileSystemInformation.md @@ -0,0 +1,62 @@ +--- +title: "FileSystemInformation" +linkTitle: "FileSystemInformation" +description: "Any data type used to represent information about a file or folder." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.FilesAndFolders.FileSystemInformation)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent information about a file or folder. + +| | | +|-|-| +| **Category:** | Files & Folders | +| **Name:** | `FileSystemInformation` | +| **Full Name:** | `Cortex.DataTypes.FilesAndFolders.FileSystemInformation` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent information about a file or folder. | +| **Default Value:** | `null` | +| **Can be used as:** | `FileSystemInformation`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `FileSystemInformation`. +- The Literal Editor is not available for [Input][] properties where the data type is `FileSystemInformation`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `FileSystemInformation`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [FileInformation][] +- [FolderInformation][] + +### Related Concepts + +- [Working With Files & Folders][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[FileInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FileInformation.MainDoc" >}} +[FolderInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FolderInformation.MainDoc" >}} + +[Working With Files & Folders]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/_index.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/_index.md new file mode 100644 index 000000000..ddae453f0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/_index.md @@ -0,0 +1,6 @@ +--- +title: "Files & Folders" +linkTitle: "Files & Folders" +description: "Data types used for working with files and folders." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/contentoptions.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/contentoptions.md new file mode 100644 index 000000000..90744c0e1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/contentoptions.md @@ -0,0 +1,76 @@ +--- +title: "ContentOptions" +linkTitle: "ContentOptions" +description: "Used to represent the set of options for the Get Folder Content block." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.FilesAndFolders.ContentOptions)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `ContentOptions` data type is used to represent the set of options for the [Get Folder Content][] block. + +`ContentOptions` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Files & Folders | +| **Name:** | `ContentOptions` | +| **Full Name:** | `Cortex.DataTypes.FilesAndFolders.ContentOptions` | +| **Alias:** | N/A | +| **Description:** | Used to represent the set of options for the [Get Folder Content][] block. | +| **Default Value:** | `(ContentOptions)0` | +| **Can be used as:** | `ContentOptions`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)ContentOptions.Files` or `(System.Int16)ContentOptions.Files` or `(short)ContentOptions.Files`) | +| | `Int32` (e.g. `(Int32)ContentOptions.Files` or `(System.Int32)ContentOptions.Files` or `(int)ContentOptions.Files`) | +| | `Int64` (e.g. `(Int64)ContentOptions.Files` or `(System.Int64)ContentOptions.Files` or `(long)ContentOptions.Files`) | +| | `Single` (e.g. `(Single)ContentOptions.Files` or `(System.Single)ContentOptions.Files` or `(float)ContentOptions.Files`) | +| | `Double` (e.g. `(Double)ContentOptions.Files` or `(System.Double)ContentOptions.Files` or `(double)ContentOptions.Files`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ContentOptions`. +- The Literal Editor is available for [Input][] properties where the data type is `ContentOptions`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ContentOptions`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working With Files & Folders][] + +### External Documentation + +- [System.Enum][] + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Get Folder Content]: {{< url path="Cortex.Reference.Blocks.FilesAndFolders.GetFolderContent.GetFolderContent.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[Working With Files & Folders]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/fileinformation.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/fileinformation.md new file mode 100644 index 000000000..7375d4493 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/fileinformation.md @@ -0,0 +1,60 @@ +--- +title: "FileInformation" +linkTitle: "FileInformation" +description: "Used to represent information about a file." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.FilesAndFolders.FileInformation)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `FileInformation` data type is used to represent information about a file. + +| | | +|-|-| +| **Category:** | Files & Folders | +| **Name:** | `FileInformation` | +| **Full Name:** | `Cortex.DataTypes.FilesAndFolders.FileInformation` | +| **Alias:** | N/A | +| **Description:** | Used to represent information about a file. | +| **Default Value:** | `null` | +| **Can be used as:** | `FileInformation`, `FileSystemInformation`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `FileInformation`. +- The Literal Editor is not available for [Input][] properties where the data type is `FileInformation`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `FileInformation`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [FolderInformation][] + +### Related Concepts + +- [Working With Files & Folders][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[FolderInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FolderInformation.MainDoc" >}} + +[Working With Files & Folders]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/filematch.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/filematch.md new file mode 100644 index 000000000..82edbdf5e --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/filematch.md @@ -0,0 +1,67 @@ +--- +title: "FileMatch" +linkTitle: "FileMatch" +description: "Used to represent a regex match of a line within a file. It contains all of the groups found in the regex pattern." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.FilesAndFolders.FileMatch)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `FileMatch` data type is used to represent a regex match of a line within a file. It contains all of the [Groups][Group] found in the regex pattern. + +| | | +|-|-| +| **Category:** | Files & Folders | +| **Name:** | `FileMatch` | +| **Full Name:** | `Cortex.DataTypes.FilesAndFolders.FileMatch` | +| **Alias:** | N/A | +| **Description:** | Used to represent a regex match of a line within a file. It contains all of the [Groups][Group] found in the regex pattern. | +| **Default Value:** | `null` | +| **Can be used as:** | `FileMatch`, `Match`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `FileMatch`. +- The Literal Editor is not available for [Input][] properties where the data type is `FileMatch`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `FileMatch`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Group][] +- [Int32][] +- [Match][] +- [String][] + +### Related Concepts + +- [Working With Files & Folders][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Group]: {{}} +[Match]: {{}} + +[Int32]: {{}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Working With Files & Folders]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/files-and-folders/folderinformation.md b/content/en/docs/2024.9/Reference/data-types/files-and-folders/folderinformation.md new file mode 100644 index 000000000..e065fb162 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/files-and-folders/folderinformation.md @@ -0,0 +1,60 @@ +--- +title: "FolderInformation" +linkTitle: "FolderInformation" +description: "Used to represent information about a folder." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.FilesAndFolders.FolderInformation)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `FolderInformation` data type is used to represent information about a folder. + +| | | +|-|-| +| **Category:** | Files & Folders | +| **Name:** | `FolderInformation` | +| **Full Name:** | `Cortex.DataTypes.FilesAndFolders.FolderInformation` | +| **Alias:** | N/A | +| **Description:** | Used to represent information about a folder. | +| **Default Value:** | `null` | +| **Can be used as:** | `FolderInformation`, `FileSystemInformation`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `FolderInformation`. +- The Literal Editor is not available for [Input][] properties where the data type is `FolderInformation`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `FolderInformation`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [FileInformation][] + +### Related Concepts + +- [Working With Files & Folders][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[FileInformation]: {{< url path="Cortex.Reference.DataTypes.FilesAndFolders.FileInformation.MainDoc" >}} + +[Working With Files & Folders]: {{< url path="Cortex.Reference.Concepts.WorkingWith.FilesAndFolders.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/flows/_index.md b/content/en/docs/2024.9/Reference/data-types/flows/_index.md new file mode 100644 index 000000000..89e426e6d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/flows/_index.md @@ -0,0 +1,6 @@ +--- +title: "Flows" +linkTitle: "Flows" +description: "Data types used for working with Flows." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/flows/flowreference.md b/content/en/docs/2024.9/Reference/data-types/flows/flowreference.md new file mode 100644 index 000000000..3cfbf6b59 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/flows/flowreference.md @@ -0,0 +1,78 @@ +--- +title: "FlowReference" +linkTitle: "FlowReference" +description: "Used to reference a Flow using its Id." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Flows.FlowReference)

+ +## Summary + +A `FlowReference` is used to reference a flow that will be called using the [Run Flow][] block. + +| | | +|-|-| +| **Category:** | Flows | +| **Name:** | `FlowReference` | +| **Full Name:** | `Cortex.DataTypes.Flows.FlowReference` | +| **Alias:** | N/A | +| **Description:** | Used to reference a Flow using its Id. | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Id + +The unique Id of the flow that is referenced. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | +| Is Advanced | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `00000000-0000-0000-0000-000000000000`) | + +## Remarks + +### Create a FlowReference + +Currently a FlowReference can only created by using the [Flow Property][] of the [Run Flow][] block. Using the editor to select a flow (by its Name or Id) will create a flow reference for the block to use. + +### Property Editor Support + +- The Expression Editor is not available for [Input][], [InputOutput][] and [Output][] properties where the data type is `FlowReference`. +- The Literal Editor is available for [Input][] properties where the data type is `FlowReference`. +- The Variable Editor is available for [Output][] properties where the data type is `FlowReference`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [Guid][] + +### Related Concepts + +- [Flows][] + +### External Documentation + +None + +[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" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} + +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} +[Flow Property]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.FlowProperty" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/flows/inputvariables.md b/content/en/docs/2024.9/Reference/data-types/flows/inputvariables.md new file mode 100644 index 000000000..9ad759806 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/flows/inputvariables.md @@ -0,0 +1,83 @@ +--- +title: "InputVariables" +linkTitle: "InputVariables" +description: "A collection of flow Input Variables." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Flows.InputVariables)

+ +## Summary + +`InputVariables` are used to pass data into a called flow when using the [Run Flow][] block. + +| | | +|-|-| +| **Category:** | Flows | +| **Name:** | `InputVariables` | +| **Full Name:** | `Cortex.DataTypes.Flows.InputVariables` | +| **Alias:** | N/A | +| **Description:** | A collection of flow Input Variables. | +| **Default Value:** | `null` | +| **Can be used as:** | `Structure`, `IDictionary`, `IEnumerable`, `Object`, `dynamic` | +| | `IEnumerable>` (e.g. where `InputVariables` is `IDictionary` and `IEnumerable>` is `IEnumerable>`) | +| **Can be cast to:** | N/A | + +## Remarks + +### Create an InputVariables + +The following table shows some of the ways that an `InputVariables` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `InputVariables` expression | `new InputVariables()` | `{}` | Expression | `InputVariables` containing zero items | +| | ``new InputVariables() { { "Variable1", true } }`` | `{ "Variable1": true }` | Expression | `InputVariables` containing one Boolean item with a String key | +| | ``new InputVariables() { { "Variable1", true }, { "Variable2", 100 } }`` | `{ "Variable1": true, "Variable2": 100 }` | Expression | `InputVariables` containing Boolean and Int32 items with String keys | + +An `InputVariables` can also be created using the Literal Editor when using the [Run Flow][] block. For more information see the [Inputs Property][] of the [Run Flow][] block. + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `InputVariables`. +- The Literal Editor is available for [Input][] properties where the data type is `InputVariables`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `InputVariables`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [IEnumerable][] +- [IEnumerable<TItem>][] +- [IDictionary<TKey, TItem>][] +- [Structure][] + +### Related Concepts + +- [Flows][] +- [Variables][] +- [Input Variables][] + +### External Documentation + +None + +[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" >}} +[Flows]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.MainDoc" >}} +[Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.MainDoc" >}} +[Input Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.FlowInputVariable" >}} + +[Run Flow]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.MainDoc" >}} +[Inputs Property]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlow.InputsProperty" >}} + +[IEnumerable]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable.MainDoc" >}} +[IEnumerable<TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IEnumerable_TItem.MainDoc" >}} +[IDictionary<TKey, TItem>]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/_index.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/_index.md new file mode 100644 index 000000000..862a37f7d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/_index.md @@ -0,0 +1,6 @@ +--- +title: "Google Workspace" +linkTitle: "Google Workspace" +description: "Data types used for working with Google Workspace blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/_index.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/_index.md new file mode 100644 index 000000000..e5f9ae55c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/_index.md @@ -0,0 +1,6 @@ +--- +title: "Gmail" +linkTitle: "Gmail" +description: "Data types used for working with Gmail blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/_index.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/_index.md new file mode 100644 index 000000000..f2d4b5ea2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/_index.md @@ -0,0 +1,6 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Data types used for authentication when working with Gmail blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/_index.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/_index.md new file mode 100644 index 000000000..ba8a0a74b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/_index.md @@ -0,0 +1,6 @@ +--- +title: "OAuth" +linkTitle: "OAuth" +description: "Data types used for authentication via OAuth when working with Gmail blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/gmailoauthcertificatecredentials.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/gmailoauthcertificatecredentials.md new file mode 100644 index 000000000..602f25759 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/authentication/oauth/gmailoauthcertificatecredentials.md @@ -0,0 +1,151 @@ +--- +title: "GmailOAuthCertificateCredentials" +linkTitle: "GmailOAuthCertificateCredentials" +description: "Used to represent configuration for authentication via OAuth when establishing a connection with a mail server hosted by Gmail." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials)

+ +## Summary + +The `GmailOAuthCertificateCredentials` data type is used to represent configuration for authentication via OAuth when establishing a connection with a mail server hosted by [Gmail][]. For more information on how to set up a [Gmail][] account so that this authentication mechanism can be used, see [Setting up a Gmail account for OAuth authentication][] + +| | | +|-|-| +| **Category:** | Gmail | +| **Name:** | `GmailOAuthCertificateCredentials` | +| **Full Name:** | `Cortex.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials` | +| **Alias:** | N/A | +| **Description:** | Configuration for authentication via OAuth when establishing a connection with a mail server hosted by [Gmail][]. | +| **Default Value:** | null | +| **Can be used as:** | `GmailOAuthCertificateCredentials`, `EmailCredentials`, `IEmailCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### CertificatePath + +The CertificatePath is used to define the path pointing to the certificate (.p12) file to be used for authentication via OAuth, the certificate file must be accessible from the server executing the flow. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### CertificatePassword + +The CertificatePassword is used to define the password associated with the certificate file at the [CertificatePath][CertificatePath Property]. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +### FromAddress + +The FromAddress is used to define the address of the account used to set up the client application created to allow authentication via OAuth. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### ClientId + +The ClientId is used to define the client ID of the client application created to allow authentication via OAuth. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +## Remarks + +### Create a GmailOAuthCertificateCredentials + +The following table shows how a `GmailOAuthCertificateCredentials` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `GmailOAuthCertificateCredentials` constructor | `new GmailOAuthCertificateCredentials(certificatePath: @"C:\certificate.p12", certificatePassword: "encryptedPassword", fromAddress: "sender@gmail.com", clientId: "clientId")` | `{"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}` | Expression | N/A | + +A `GmailOAuthCertificateCredentials` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `CertificatePath` | `EncryptableText` | `$@"C:\certificate.p12"` | The [CertificatePath][CertificatePath Property] defines the path pointing to the certificate (.p12) file to be used for authentication via OAuth. | +| `CertificatePassword` | `EncryptedText` | `"encryptedPassword"` | The [CertificatePassword][CertificatePassword Property] defines the password associated with the certificate file at the [CertificatePath][CertificatePath Property]. | +| `FromAddress` | `String` | `"sender@gmail.com"` | The [FromAddress][FromAddress Property] defines the address of the account used to set up the client application created to allow authentication via OAuth. | +| `ClientId` | `EncryptableText` | `"clientid"` | The [ClientId][ClientId Property] defines the client ID of the client application created to allow authentication via OAuth. | + +### Convert GmailOAuthCertificateCredentials to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}` | `"{\r\n \"CertificatePath\": \"C:\\\\certificate.p12\",\r\n \"CertificatePassword\": \"encryptedPassword\",\r\n \"FromAddress\": \"sender@gmail.com\",\r\n \"ClientId\": \"clientId\"\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `GmailOAuthCertificateCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `GmailOAuthCertificateCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `GmailOAuthCertificateCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EmailCredentials][] +- [EncryptedText][] +- [EncryptableText][] +- [GmailSessionDetails][] +- [IEmailCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[CertificatePath Property]: {{< ref "#certificatepath" >}} +[CertificatePassword Property]: {{< ref "#certificatepassword" >}} +[FromAddress Property]: {{< ref "#fromaddress" >}} +[ClientId Property]: {{< ref "#clientid" >}} + +[GmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails.MainDoc" >}} +[IEmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.IEmailCredentials.MainDoc" >}} +[EmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.EmailCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} +[Setting up a Gmail account for OAuth authentication]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.Authentication.SettingUpOAuthGmail" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Gmail]: {{< url path="Cortex.Reference.Glossary.F-J.Gmail" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/gmailsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/gmailsessiondetails.md new file mode 100644 index 000000000..c12795552 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/google-workspace/gmail/gmailsessiondetails.md @@ -0,0 +1,161 @@ +--- +title: "GmailSessionDetails" +linkTitle: "GmailSessionDetails" +description: "Used to represent configuration for opening and maintaining a session with a mail server hosted by Gmail." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails)

+ +## Summary + +The `GmailSessionDetails` data type is used to represent configuration for opening and maintaining a session with a mail server hosted by [Gmail][]. + +| | | +|-|-| +| **Category:** | Gmail | +| **Name:** | `GmailSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Configuration for opening and maintaining a session with a mail server hosted by [Gmail][]. | +| **Default Value:** | null | +| **Can be used as:** | `GmailSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ServerDetails + +The ServerDetails are used to configure the [Host][] and [Port][] of the mail server to connect to and whether or not to [UseSsl][]. + +| | | +|--------------------|---------------------------| +| Data Type | [ServerDetails][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [ServerDetails][] with value shown below: | + +```json +{ + "Host": "", + "Port": 465, + "UseSsl": true +} +``` + +### Credentials + +The Credentials are used to configure the information required for authentication with the mail server. There are multiple data types that can be used: + +- [UserCredentials][]: Used to configure the [Username][] and [Password][] for Basic authentication +- [GmailOAuthCertificateCredentials][]: Used to configure the [CertificatePath][], [CertificatePassword][], [FromAddress][] and [ClientId][] for OAuth + +| | | +|--------------------|---------------------------| +| Data Type | [IEmailCredentials][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [UserCredentials][] with value shown below: | + +```json +{ + "Domain": "", + "Username": "", + "Password": "" +} +``` + +## Remarks + +### Create a GmailSessionDetails + +The following table shows some of the ways that `GmailSessionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `GmailSessionDetails` constructor | `new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))` | `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}` | Expression | The [Password][] property in the [UserCredentials][] can be 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 up an app password for a Gmail account][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | +| | `new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new GmailOAuthCertificateCredentials(@"C:\certificate.p12", "encryptedPassword", "sender@gmail.com", "clientId")` | `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}}` | Expression | The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] is a path pointing to a certificate accessible from the server executing the flow.

For information on:
  • What each of the properties in the [GmailOAuthCertificateCredentials][] needs to be, see [GmailOAuthCertificateCredentials][]
  • How to set up the [Gmail][] account so that this authentication mechanism can be used, see [Setting up a Gmail account for OAuth authentication][]
The [CertificatePassword][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | + +A `GmailSessionDetails` with a [UserCredentials][] as the [Credentials][Credentials Property] can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `ServerDetails` | `ServerDetails` | Host: `"smtp.gmail.com"`
Port: `465`
UseSsl: `true` | The [ServerDetails][ServerDetails Property] that are used to connect to the server. | +| `Credentials` | `UserCredentials` | Domain: `""`
Username: `"sender@gmail.com"`
Password: `"encryptedPassword"` | The [Credentials][Credentials Property] that are used for authentication on the server.

The [Password][] property in the [UserCredentials][] can be 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 up an app password for a Gmail account][].

The [Password][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][]. | + +A `GmailSessionDetails` with a [GmailOAuthCertificateCredentials][] as the [Credentials][Credentials Property] can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `ServerDetails` | `ServerDetails` | Host: `"smtp.gmail.com"`
Port: `465`
UseSsl: `true` | The [ServerDetails][ServerDetails Property] that are used to connect to the server. | +| `Credentials` | `GmailOAuthCertificateCredentials` | CertificatePath: `$@"C:\certificate.p12"`
CertificatePassword: `"encryptedPassword"`
FromAddress: `"sender@gmail.com"`
ClientId: `"clientId"` | The [Credentials][Credentials Property] that are used for authentication on the server.

The [CertificatePath][] in the [GmailOAuthCertificateCredentials][] is a path pointing to a certificate which must be accessible from the server executing the flow.

For information on:
  • What each of the properties in the [GmailOAuthCertificateCredentials][] needs to be, see [GmailOAuthCertificateCredentials][]
  • How to set up the [Gmail][] account so that this authentication mechanism can be used, see [Setting up a Gmail account for OAuth authentication][]
The [CertificatePassword][] property must be encrypted, for more information on how to encrypt the password, see [EncryptedText][].| + +### Convert GmailSessionDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}` | `"{\r\n \"ServerDetails\": {\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n },\r\n \"Credentials\": {\r\n \"Domain\": null,\r\n \"Username\": \"sender@gmail.com\",\r\n \"Password\": \"encryptedPassword\"\r\n }\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `GmailSessionDetails`. +- The Literal Editor is available for [Input][] properties where the data type is `GmailSessionDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `GmailSessionDetails`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptedText][] +- [GmailOAuthCertificateCredentials][] +- [ServerDetails][] +- [UserCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[ServerDetails Property]: {{< ref "#serverdetails" >}} +[Credentials Property]: {{< ref "#credentials" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} + +[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" >}} + +[IEmailCredentials]: {{< url path="Cortex.Reference.DataTypes.Email.Authentication.IEmailCredentials.MainDoc" >}} + +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} +[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" >}} + +[Gmail]: {{< url path="Cortex.Reference.Glossary.F-J.Gmail" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/_index.md b/content/en/docs/2024.9/Reference/data-types/http/_index.md new file mode 100644 index 000000000..6e85c0f39 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/_index.md @@ -0,0 +1,6 @@ +--- +title: "Http" +linkTitle: "Http" +description: "Data types used for working with HTTP." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpCredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpCredentials.md new file mode 100644 index 000000000..dde6d4fd2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpCredentials.md @@ -0,0 +1,67 @@ +--- +title: "HttpCredentials" +linkTitle: "HttpCredentials" +description: "Any data type used to represent details required for authentication when working with HTTP." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.HttpCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required for authentication when working with HTTP. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `HttpCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.HttpCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required for authentication when working with HTTP. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpCredentials`, `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [HttpOAuthClientCredentials][] +- [HttpOAuthCredentials][] +- [HttpOAuthPasswordCredentials][] +- [HttpUserCredentials][] +- [IHttpCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpOAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials.MainDoc" >}} +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} +[HttpUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpUserCredentials.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpUserCredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpUserCredentials.md new file mode 100644 index 000000000..ecaaee456 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/HttpUserCredentials.md @@ -0,0 +1,61 @@ +--- +title: "HttpUserCredentials" +linkTitle: "HttpUserCredentials" +description: "Used to represent details required for basic authentication when working with HTTP." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.HttpUserCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpUserCredentials` data type is used to represent details required for basic authentication when working with HTTP. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `HttpUserCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.HttpUserCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent details required for basic authentication when working with HTTP. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpUserCredentials`, `HttpCredentials`, `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpUserCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpUserCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpUserCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [HttpCredentials][] +- [IHttpCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/IHttpCredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/IHttpCredentials.md new file mode 100644 index 000000000..f536b1fe2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/IHttpCredentials.md @@ -0,0 +1,67 @@ +--- +title: "IHttpCredentials" +linkTitle: "IHttpCredentials" +description: "Any data type used to represent details required for authentication when working with HTTP." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.IHttpCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required for authentication when working with HTTP. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `IHttpCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.IHttpCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required for authentication when working with HTTP. | +| **Default Value:** | `null` | +| **Can be used as:** | `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `IHttpCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `IHttpCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `IHttpCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [HttpCredentials][] +- [HttpOAuthClientCredentials][] +- [HttpOAuthCredentials][] +- [HttpOAuthPasswordCredentials][] +- [HttpUserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpUserCredentials.MainDoc" >}} +[HttpOAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials.MainDoc" >}} +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/_index.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/_index.md new file mode 100644 index 000000000..56f986971 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/_index.md @@ -0,0 +1,6 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Data types used for authentication when working with HTTP." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/_index.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/_index.md new file mode 100644 index 000000000..79d2d973d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/_index.md @@ -0,0 +1,6 @@ +--- +title: "OAuth" +linkTitle: "OAuth" +description: "Data types used for authentication via OAuth when working with HTTP." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthentication.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthentication.md new file mode 100644 index 000000000..2720cd459 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthentication.md @@ -0,0 +1,109 @@ +--- +title: "ClientAuthentication" +linkTitle: "ClientAuthentication" +description: "Used to represent the `ClientId` and `ClientSecret` required for OAuth authentication mechanisms that use Client Secrets." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthentication)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `ClientAuthentication` data type is used to represent the `ClientId` and `ClientSecret` required for OAuth authentication mechanisms that use Client Secrets. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `ClientAuthentication` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthentication` | +| **Alias:** | N/A | +| **Description:** | Used to represent the `ClientId` and `ClientSecret` required for OAuth authentication mechanisms that use Client Secrets. | +| **Default Value:** | `null` | +| **Can be used as:** | `ClientAuthentication`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ClientId + +The ClientId is used to define the client ID assigned to {{% ctx %}} by the OAuth provider, to allow it to authenticate. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### ClientSecret + +The ClientSecret is used to define the client secret assigned to {{% ctx %}} by the OAuth provider, to allow it to authenticate; this value should be kept secret. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +### SendAs + +The SendAs is used to specify whether the [ClientId][] and [ClientSecret][] are included as part of the HTTP request body or headers. + +| | | +|--------------------|---------------------------| +| Data Type | [ClientAuthType][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Header` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ClientAuthentication`. +- The Literal Editor is available for [Input][] properties where the data type is `ClientAuthentication`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ClientAuthentication`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ClientAuthType][] +- [EncryptableText][] +- [EncryptedText][] +- [HttpOAuthClientCredentials][] +- [HttpOAuthPasswordCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[ClientId]: {{< ref "#clientid">}} +[Clientsecret]: {{< ref "#clientsecret">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} +[ClientAuthType]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthType.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthtype.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthtype.md new file mode 100644 index 000000000..4e4c2a577 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/clientauthtype.md @@ -0,0 +1,78 @@ +--- +title: "ClientAuthType" +linkTitle: "ClientAuthType" +description: "Used to represent whether the `ClientId` and `ClientSecret` specified in ClientAuthentication are sent as part of the HTTP headers or HTTP body." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthType)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `ClientAuthType` data type is used to represent whether the `ClientId` and `ClientSecret` specified in [ClientAuthentication][] are sent as part of the HTTP headers or HTTP body. + +`ClientAuthType` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `ClientAuthType` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthType` | +| **Alias:** | N/A | +| **Description:** | Used to represent whether the `ClientId` and `ClientSecret` specified in [ClientAuthentication][] are sent as part of the HTTP headers or HTTP body. | +| **Default Value:** | `(ClientAuthType)0` | +| **Can be used as:** | `ClientAuthType`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)ClientAuthType.Header` or `(System.Int16)ClientAuthType.Header` or `(short)ClientAuthType.Header`) | +| | `Int32` (e.g. `(Int32)ClientAuthType.Header` or `(System.Int32)ClientAuthType.Header` or `(int)ClientAuthType.Header`) | +| | `Int64` (e.g. `(Int64)ClientAuthType.Header` or `(System.Int64)ClientAuthType.Header` or `(long)ClientAuthType.Header`) | +| | `Single` (e.g. `(Single)ClientAuthType.Header` or `(System.Single)ClientAuthType.Header` or `(float)ClientAuthType.Header`) | +| | `Double` (e.g. `(Double)ClientAuthType.Header` or `(System.Double)ClientAuthType.Header` or `(double)ClientAuthType.Header`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ClientAuthType`. +- The Literal Editor is available for [Input][] properties where the data type is `ClientAuthType`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ClientAuthType`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ClientAuthentication][] +- [HttpOAuthClientCredentials][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[ClientAuthentication]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthclientcredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthclientcredentials.md new file mode 100644 index 000000000..558b317ac --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthclientcredentials.md @@ -0,0 +1,115 @@ +--- +title: "HttpOAuthClientCredentials" +linkTitle: "HttpOAuthClientCredentials" +description: "Used to represent details required for the OAuth Client Credentials authentication mechanism." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpOAuthClientCredentials` data type is used to represent details required for the OAuth Client Credentials authentication mechanism. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `HttpOAuthClientCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent details required for the OAuth Client Credentials authentication mechanism. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpOAuthClientCredentials`, `HttpOAuthCredentials`, `HttpCredentials`, `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### AccessTokenUri + +The AccessTokenUri represents the URI used to get the access token. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|-----------------|---------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### ClientAuthentication + +The ClientAuthentication represents the [ClientId][], [ClientSecret][] and [SendAs][]. + +| | | +|-----------------|--------------------------| +| Data Type | [ClientAuthentication][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [ClientAuthentication][] with no value | + +### Scope + +The scope of permissions being requested for the access token. For multiple scopes, each scope should be separated by a space (e.g. `"Scope1 Scope2"`). + +| | | +|-----------------|-------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpOAuthClientCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpOAuthClientCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpOAuthClientCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ClientAuthentication][] +- [EncryptableText][] +- [HttpCredentials][] +- [HttpOAuthCredentials][] +- [HttpOAuthPasswordCredentials][] +- [IHttpCredentials][] +- [String][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpOAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials.MainDoc" >}} +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[ClientAuthentication]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[ClientId]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientId" >}} +[ClientSecret]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientSecret" >}} +[SendAs]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.SendAs" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthcredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthcredentials.md new file mode 100644 index 000000000..19b5983f9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthcredentials.md @@ -0,0 +1,65 @@ +--- +title: "HttpOAuthCredentials" +linkTitle: "HttpOAuthCredentials" +description: "Any data type used to represent details required for OAuth authentication." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required for OAuth authentication. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `HttpOAuthCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required for OAuth authentication. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpOAuthCredentials`, `HttpCredentials`, `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpOAuthCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpOAuthCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpOAuthCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [HttpCredentials][] +- [HttpOAuthClientCredentials][] +- [HttpOAuthPasswordCredentials][] +- [IHttpCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} +[HttpOAuthPasswordCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthpasswordcredentials.md b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthpasswordcredentials.md new file mode 100644 index 000000000..6692a199c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/authentication/oauth/httpoauthpasswordcredentials.md @@ -0,0 +1,140 @@ +--- +title: "HttpOAuthPasswordCredentials" +linkTitle: "HttpOAuthPasswordCredentials" +description: "Used to represent details required for the OAuth Resource Owner Password Credentials authentication mechanism." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpOAuthPasswordCredentials` data type is used to represent details required for the OAuth Resource Owner Password Credentials authentication mechanism. + +| | | +|---------------------|----------------------------------------------------------------------------------------------------------------| +| **Category:** | Http | +| **Name:** | `HttpOAuthPasswordCredentials` | +| **Full Name:** | `Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent details required for the OAuth Resource Owner Password Credentials authentication mechanism. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpOAuthPasswordCredentials`, `HttpCredentials`, `IHttpCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### AccessTokenUri + +The AccessTokenUri represents the URI used to get the access token. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|-----------------|-------------------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText] with value `$@""` | + +### ClientAuthentication + +The ClientAuthentication represents the [ClientId][], [ClientSecret][] and [SendAs][]. + +| | | +|-----------------|--------------------------------------| +| Data Type | [ClientAuthentication][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [ClientAuthentication] with no value | + +### Scope + +The scope of permissions being requested for the access token. For multiple scopes, each scope should be separated by a space (e.g. `"Scope1 Scope2"`). + +| | | +|-----------------|----------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### ResourceOwnerUsername + +The ResourceOwnerUsername is the username used to get the access token. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|-----------------|-------------------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### ResourceOwnerPassword + +The ResourceOwnerPassword is the password associated with the [ResourceOwnerUsername][]. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|-----------------|-----------------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpOAuthPasswordCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpOAuthPasswordCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpOAuthPasswordCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ClientAuthentication][] +- [EncryptableText][] +- [EncryptedText][] +- [HttpCredentials][] +- [HttpOAuthClientCredentials][] +- [HttpOAuthCredentials][] +- [IHttpCredentials][] +- [String][] + +### Related Concepts + +None + +### External Documentation + +None + +[ResourceOwnerUsername]: {{< ref "#resourceownerusername">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[IHttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.IHttpCredentials.MainDoc" >}} +[HttpCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.HttpCredentials.MainDoc" >}} +[HttpOAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials.MainDoc" >}} +[HttpOAuthClientCredentials]: {{< url path="Cortex.Reference.DataTypes.Http.Authentication.OAuth.HttpOAuthClientCredentials.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} +[ClientAuthentication]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.MainDoc" >}} +[ClientId]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientId" >}} +[ClientSecret]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.ClientSecret" >}} +[SendAs]: {{< url path = "Cortex.Reference.DataTypes.Http.Authentication.OAuth.ClientAuthentication.SendAs" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/httprequestversion.md b/content/en/docs/2024.9/Reference/data-types/http/httprequestversion.md new file mode 100644 index 000000000..903447eec --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/httprequestversion.md @@ -0,0 +1,89 @@ +--- +title: "HttpRequestVersion" +linkTitle: "HttpRequestVersion" +description: "Used to represent the version of HTTP to be used when making an HTTP request." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.HttpRequestVersion)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpRequestVersion` data type is used to represent the version of HTTP to be used when making an HTTP request. + +`HttpRequestVersion` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| **Category:** | Http | +| **Name:** | `HttpRequestVersion` | +| **Full Name:** | `Cortex.DataTypes.Http.HttpRequestVersion` | +| **Alias:** | N/A | +| **Description:** | Used to represent the version of HTTP to be used when making an HTTP request. | +| **Default Value:** | `(HttpRequestVersion)0` | +| **Can be used as:** | `HttpRequestVersion`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)HttpRequestVersion.HTTP10` or `(System.Int16)HttpRequestVersion.HTTP10` or `(short)HttpRequestVersion.HTTP10`) | +| | `Int32` (e.g. `(Int32)HttpRequestVersion.HTTP10` or `(System.Int32)HttpRequestVersion.HTTP10` or `(int)HttpRequestVersion.HTTP10`) | +| | `Int64` (e.g. `(Int64)HttpRequestVersion.HTTP10` or `(System.Int64)HttpRequestVersion.HTTP10` or `(long)HttpRequestVersion.HTTP10`) | +| | `Single` (e.g. `(Single)HttpRequestVersion.HTTP10` or `(System.Single)HttpRequestVersion.HTTP10` or `(float)HttpRequestVersion.HTTP10`) | +| | `Double` (e.g. `(Double)HttpRequestVersion.HTTP10` or `(System.Double)HttpRequestVersion.HTTP10` or `(double)HttpRequestVersion.HTTP10`) | + +## Values + +### HTTP10 + +| | | +|------------|---------------------------| +| **Name:** | HTTP10 | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | HTTP 1.0 request version. | + +### HTTP11 + +| | | +|------------|---------------------------| +| **Name:** | HTTP11 | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | HTTP 1.1 request version. | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpRequestVersion`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpRequestVersion`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpRequestVersion`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/httpstatuscode.md b/content/en/docs/2024.9/Reference/data-types/http/httpstatuscode.md new file mode 100644 index 000000000..45fd32d2e --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/httpstatuscode.md @@ -0,0 +1,80 @@ +--- +title: "HttpStatusCode" +linkTitle: "HttpStatusCode" +description: "Used to represent the status code returned by an HTTP request." +weight: 1 +--- + +# {{% param title %}} + +

(System.Net.HttpStatusCode)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpStatusCode` data type is used to represent the status code returned by an HTTP request. + +`HttpStatusCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------------------------------| +| **Category:** | Http | +| **Name:** | `HttpStatusCode` | +| **Full Name:** | `System.Net.HttpStatusCode` | +| **Alias:** | N/A | +| **Description:** | Used to represent the status code returned by an HTTP request. | +| **Default Value:** | `(HttpStatusCode)0` | +| **Can be used as:** | `HttpStatusCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)HttpStatusCode.Continue` or `(System.Int16)HttpStatusCode.Continue` or `(short)HttpStatusCode.Continue`) | +| | `Int32` (e.g. `(Int32)HttpStatusCode.Continue` or `(System.Int32)HttpStatusCode.Continue` or `(int)HttpStatusCode.Continue`) | +| | `Int64` (e.g. `(Int64)HttpStatusCode.Continue` or `(System.Int64)HttpStatusCode.Continue` or `(long)HttpStatusCode.Continue`) | +| | `Single` (e.g. `(Single)HttpStatusCode.Continue` or `(System.Single)HttpStatusCode.Continue` or `(float)HttpStatusCode.Continue`) | +| | `Double` (e.g. `(Double)HttpStatusCode.Continue` or `(System.Double)HttpStatusCode.Continue` or `(double)HttpStatusCode.Continue`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpStatusCode`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpStatusCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpStatusCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [HttpResponse][] +- [SoapResponse][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] +- [System.Net.HttpStatusCode][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[HttpResponse]: {{< url path = "Cortex.Reference.DataTypes.Http.Rest.HttpResponse.MainDoc" >}} +[SoapResponse]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapResponse.MainDoc" >}} +[System.Net.HttpStatusCode]: {{< url path="MSDocs.DotNet.Api.System.Net.HttpStatusCode" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/request.md b/content/en/docs/2024.9/Reference/data-types/http/request.md new file mode 100644 index 000000000..f38557d59 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/request.md @@ -0,0 +1,63 @@ +--- +title: "Request" +linkTitle: "Request" +description: "Any data type that is used to represent an HTTP request." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Request)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type that is used to represent an HTTP request. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `Request` | +| **Full Name:** | `Cortex.DataTypes.Http.Request` | +| **Alias:** | N/A | +| **Description:** | Any data type that is used to represent an HTTP request. | +| **Default Value:** | `null` | +| **Can be used as:** | `Request`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Request`. +- The Literal Editor is available for [Input][] properties where the data type is `Request`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Request`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [HttpRequestVersion][] +- [HttpRequest][] +- [SoapRequest][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[HttpRequestVersion]: {{< url path = "Cortex.Reference.DataTypes.Http.HttpRequestVersion.MainDoc" >}} +[HttpRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Rest.HttpRequest.MainDoc" >}} +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/requestverb.md b/content/en/docs/2024.9/Reference/data-types/http/requestverb.md new file mode 100644 index 000000000..f2a399ff4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/requestverb.md @@ -0,0 +1,130 @@ +--- +title: "RequestVerb" +linkTitle: "RequestVerb" +description: "Used to represent the type of an HTTP request." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.RequestVerb)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `RequestVerb` data type is used to represent the type of an HTTP request. + +`RequestVerb` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------| +| **Category:** | Http | +| **Name:** | `RequestVerb` | +| **Full Name:** | `Cortex.DataTypes.Http.RequestVerb` | +| **Alias:** | N/A | +| **Description:** | Used to represent the type of an HTTP request. | +| **Default Value:** | `(RequestVerb)0` | +| **Can be used as:** | `RequestVerb`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)RequestVerb.GET` or `(System.Int16)RequestVerb.GET` or `(short)RequestVerb.GET`) | +| | `Int32` (e.g. `(Int32)RequestVerb.GET` or `(System.Int32)RequestVerb.GET` or `(int)RequestVerb.GET`) | +| | `Int64` (e.g. `(Int64)RequestVerb.GET` or `(System.Int64)RequestVerb.GET` or `(long)RequestVerb.GET`) | +| | `Single` (e.g. `(Single)RequestVerb.GET` or `(System.Single)RequestVerb.GET` or `(float)RequestVerb.GET`) | +| | `Double` (e.g. `(Double)RequestVerb.GET` or `(System.Double)RequestVerb.GET` or `(double)RequestVerb.GET`) | + +## Values + +### GET + +| | | +|------------|--------------------------| +| **Name:** | GET | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | GET request. | + +### POST + +| | | +|------------|--------------------------| +| **Name:** | POST | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | POST request. | + +### PUT + +| | | +|------------|--------------------------| +| **Name:** | PUT | +| **Value:** | [Int32][] with value `2` | +| **Notes:** | PUT request. | + +### DELETE + +| | | +|------------|--------------------------| +| **Name:** | DELETE | +| **Value:** | [Int32][] with value `3` | +| **Notes:** | DELETE request. | + +### PATCH + +| | | +|------------|--------------------------| +| **Name:** | PATCH | +| **Value:** | [Int32][] with value `4` | +| **Notes:** | PATCH request. | + +### HEAD + +| | | +|------------|--------------------------| +| **Name:** | HEAD | +| **Value:** | [Int32][] with value `5` | +| **Notes:** | HEAD request. | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `RequestVerb`. +- The Literal Editor is available for [Input][] properties where the data type is `RequestVerb`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `RequestVerb`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [Request][] +- [HttpRequest][] +- [SoapRequest][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Request]: {{< url path = "Cortex.Reference.DataTypes.Http.Request.MainDoc" >}} +[HttpRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Rest.HttpRequest.MainDoc" >}} +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/rest/_index.md b/content/en/docs/2024.9/Reference/data-types/http/rest/_index.md new file mode 100644 index 000000000..1b88e585b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/rest/_index.md @@ -0,0 +1,6 @@ +--- +title: "Rest" +linkTitle: "Rest" +description: "Data types used when working with REST." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/http/rest/httprequest.md b/content/en/docs/2024.9/Reference/data-types/http/rest/httprequest.md new file mode 100644 index 000000000..84171dcde --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/rest/httprequest.md @@ -0,0 +1,156 @@ +--- +title: "HttpRequest" +linkTitle: "HttpRequest" +description: "Used to represent an HTTP REST request." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Rest.HttpRequest)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpRequest` data type is used to represent an HTTP REST request. + +| | | +|---------------------|-----------------------------------------------| +| **Category:** | Http | +| **Name:** | `HttpRequest` | +| **Full Name:** | `Cortex.DataTypes.Http.Rest.HttpRequest` | +| **Alias:** | N/A | +| **Description:** | Used to represent an HTTP REST request. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpRequest`, `Request`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Uri + +The Uri represents the endpoint to send the REST request to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|-----------------|---------------------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### QueryParameters + +The QueryParameters represents the parameters to use in the REST request; these are appended as query string parameters to the Uri. + +| | | +|-----------------|---------------------------------------------| +| Data Type | [IDictionary][IDictionary] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][IDictionary] with no value | + +### Verb + +The Verb represents the type of HTTP operation to use in the REST request. + +| | | +|-----------------|-----------------| +| Data Type | [RequestVerb][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `GET` | + +### ContentType + +The ContentType represents the type of the content used in the REST request. + +| | | +|-----------------|--------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String] with value `"application/json"` | + +### Headers + +The Headers represents the HTTP headers to include with the REST request. + +| | | +|-----------------|---------------------------------------------| +| Data Type | [IDictionary][IDictionary] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][IDictionary] with no value | + +### Body + +The data to include in the body to be used (not relevant in GET and HEAD requests). The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|-----------------|---------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### HttpVersion + +The HttpVersion represents the version of HTTP to use in the REST request. + +| | | +|-----------------|------------------------| +| Data Type | [HttpRequestVersion][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `HTTP10` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpRequest`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpRequest`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpRequest`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [HttpRequestVersion][] +- [HttpResponse][] +- [IDictionary][IDictionary] +- [Request][] +- [RequestVerb][] +- [String][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Request]: {{< url path = "Cortex.Reference.DataTypes.Http.Request.MainDoc" >}} +[HttpResponse]: {{< url path = "Cortex.Reference.DataTypes.Http.Rest.HttpResponse.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} + +[RequestVerb]: {{< url path = "Cortex.Reference.DataTypes.Http.RequestVerb.MainDoc" >}} +[HttpRequestVersion]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/rest/httpresponse.md b/content/en/docs/2024.9/Reference/data-types/http/rest/httpresponse.md new file mode 100644 index 000000000..055bc2ad9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/rest/httpresponse.md @@ -0,0 +1,121 @@ +--- +title: "HttpResponse" +linkTitle: "HttpResponse" +description: "Used to represent an HTTP REST response." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Rest.HttpResponse)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `HttpResponse` data type is used to represent an HTTP REST response. + +| | | +|---------------------|-------------------------------------------| +| **Category:** | Http | +| **Name:** | `HttpResponse` | +| **Full Name:** | `Cortex.DataTypes.Http.Rest.HttpResponse` | +| **Alias:** | N/A | +| **Description:** | Used to represent an HTTP REST response. | +| **Default Value:** | `null` | +| **Can be used as:** | `HttpResponse`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ResponseBody + +The ResponseBody represents the body of the REST response. + +| | | +|-----------------|----------------------------| +| Data Type | [dynamic][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String] with value `$@""` | + +### ErrorMessage + +The ErrorMessage is used represent any errors that occurred when executing the REST request. + +| | | +|-----------------|----------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String] with value `$@""` | + +### Headers + +The Headers are used to represent the HTTP headers returned in the REST response. + +| | | +|-----------------|---------------------------------------------------------| +| Data Type | [Dictionary][Dictionary] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Dictionary][Dictionary] with no value | + +### StatusCode + +The StatusCode is the status returned in the REST response. + +| | | +|-----------------|--------------------| +| Data Type | [HttpStatusCode][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `OK` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `HttpResponse`. +- The Literal Editor is available for [Input][] properties where the data type is `HttpResponse`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `HttpResponse`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Dictionary][Dictionary] +- [dynamic][] +- [HttpRequest][] +- [HttpStatusCode][] +- [String][] + +### Related Concepts + +None + +### External Documentation + +- [System.Net.HttpStatusCode][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[HttpRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Rest.HttpRequest.MainDoc" >}} + +[HttpStatusCode]: {{< url path = "Cortex.Reference.DataTypes.Http.HttpStatusCode.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Dictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.Dictionary.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[System.Net.HttpStatusCode]: {{< url path="MSDocs.DotNet.Api.System.Net.HttpStatusCode" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/_index.md b/content/en/docs/2024.9/Reference/data-types/http/soap/_index.md new file mode 100644 index 000000000..a78a426af --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/_index.md @@ -0,0 +1,6 @@ +--- +title: "Soap" +linkTitle: "Soap" +description: "Data types used when working with SOAP." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/soap11message.md b/content/en/docs/2024.9/Reference/data-types/http/soap/soap11message.md new file mode 100644 index 000000000..bea4c667c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/soap11message.md @@ -0,0 +1,116 @@ +--- +title: "Soap11Message" +linkTitle: "Soap11Message" +description: "Used to represent a SOAP 1.1 message." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Soap.Soap11Message)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `Soap11Message` data type is used to represent a SOAP 1.1 message. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `Soap11Message` | +| **Full Name:** | `Cortex.DataTypes.Http.Soap.Soap11Message` | +| **Alias:** | N/A | +| **Description:** | Used to represent a SOAP 1.1 message. | +| **Default Value:** | `null` | +| **Can be used as:** | `Soap11Message`, `SoapMessage`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Action + +The Action represents the SOAP action to use in the SOAP request. +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `""` | + +### Envelope + +The Envelope represents the content of the SOAP message. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Version + +The Version represents the SOAP version of the SOAP message. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | N/A see [Version is read-only][]| +| Default Editor | N/A see [Version is read-only][]| +| Default Value | [Int32] with value `11` | + +## Remarks + +### Version is read-only + +[Version][Version Property] is a read-only property set to `11` and as such will not be visible in the property editor. + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Soap11Message`. +- The Literal Editor is available for [Input][] properties where the data type is `Soap11Message`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Soap11Message`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [Int32] +- [Soap12Message][] +- [SoapMessage][] +- [SoapRequest][] +- [String][] + +### Related Concepts + +None + +### External Documentation + +None + +[Version Property]: {{< ref "#version" >}} +[Version is Read-only]: {{< ref "#version-is-read-only" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Soap12Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap12Message.MainDoc" >}} +[SoapMessage]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapMessage.MainDoc" >}} + +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/soap12message.md b/content/en/docs/2024.9/Reference/data-types/http/soap/soap12message.md new file mode 100644 index 000000000..d2e7946b8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/soap12message.md @@ -0,0 +1,64 @@ +--- +title: "Soap12Message" +linkTitle: "Soap12Message" +description: "Used to represent a SOAP 1.2 message." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Soap.Soap12Message)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `Soap12Message` data type is used to represent a SOAP 1.2 message. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `Soap12Message` | +| **Full Name:** | `Cortex.DataTypes.Http.Soap.Soap12Message` | +| **Alias:** | N/A | +| **Description:** | Used to represent a SOAP 1.2 message. | +| **Default Value:** | `null` | +| **Can be used as:** | `Soap12Message`, `SoapMessage`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Soap12Message`. +- The Literal Editor is available for [Input][] properties where the data type is `Soap12Message`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Soap12Message`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Soap11Message][] +- [SoapMessage][] +- [SoapRequest][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Soap11Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap11Message.MainDoc" >}} +[SoapMessage]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapMessage.MainDoc" >}} + +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/soapmessage.md b/content/en/docs/2024.9/Reference/data-types/http/soap/soapmessage.md new file mode 100644 index 000000000..d5a56fef0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/soapmessage.md @@ -0,0 +1,101 @@ +--- +title: "SoapMessage" +linkTitle: "SoapMessage" +description: "Any data type that is used to represent a SOAP message." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Soap.SoapMessage)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type that is used to represent a SOAP message. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `SoapMessage` | +| **Full Name:** | `Cortex.DataTypes.Http.Soap.SoapMessage` | +| **Alias:** | N/A | +| **Description:** | Any data type that is used to represent a SOAP message. | +| **Default Value:** | `null` | +| **Can be used as:** | `SoapMessage`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Envelope + +The Envelope represents the content of the SOAP message. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### Version + +The Version represents the SOAP version of the SOAP message. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | N/A see [Version is read-only][]| +| Default Editor | N/A see [Version is read-only][]| +| Default Value | [Int32] with value `11` or `12` set by [Soap11Message][] or [Soap12Message][] respectively | + +## Remarks + +### Version is read-only + +[Version][Version Property] is a read-only property set by the derived classes [Soap11Message][] and [Soap12Message][] and as such will not be visible in the property editor. + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SoapMessage`. +- The Literal Editor is available for [Input][] properties where the data type is `SoapMessage`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SoapMessage`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [Int32][] +- [Soap11Message][] +- [Soap12Message][] +- [SoapRequest][] + +### Related Concepts + +None + +### External Documentation + +None + +[Version Property]: {{< ref "#version" >}} +[Version is Read-only]: {{< ref "#version-is-read-only" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Soap12Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap12Message.MainDoc" >}} +[Soap11Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap11Message.MainDoc" >}} +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/soaprequest.md b/content/en/docs/2024.9/Reference/data-types/http/soap/soaprequest.md new file mode 100644 index 000000000..e183035ba --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/soaprequest.md @@ -0,0 +1,133 @@ +--- +title: "SoapRequest" +linkTitle: "SoapRequest" +description: "Used to represent a SOAP request." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Soap.SoapRequest)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `SoapRequest` data type is used to represent a SOAP request. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `SoapRequest` | +| **Full Name:** | `Cortex.DataTypes.Http.Soap.SoapRequest` | +| **Alias:** | N/A | +| **Description:** | Used to represent a SOAP request. | +| **Default Value:** | `null` | +| **Can be used as:** | `SoapRequest`, `Request`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Uri + +The Uri represents the endpoint to send the SOAP message to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### SoapMessage + +The SoapMessage represents the SOAP message to send. + +| | | +|--------------------|---------------------------| +| Data Type | [SoapMessage][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [SoapMessage] with value shown below | + +```json +{ + "Action": "", + "Envelope": "", + "Version": 11 +} +``` + +### Headers + +The Headers are used to represent the HTTP headers to add to the request. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][IDictionary] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][IDictionary] with no value | + +### HttpVersion + +The HttpVersion represents the version of HTTP to use in the request. + +| | | +|--------------------|---------------------------| +| Data Type | [HttpRequestVersion][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `HTTP10` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SoapRequest`. +- The Literal Editor is available for [Input][] properties where the data type is `SoapRequest`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SoapRequest`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [HttpRequestVersion][] +- [IDictionary][IDictionary] +- [Request][] +- [Soap11Message][] +- [Soap12Message][] +- [SoapMessage][] +- [SoapResponse][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Soap11Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap11Message.MainDoc" >}} +[Soap12Message]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.Soap12Message.MainDoc" >}} +[Request]: {{< url path = "Cortex.Reference.DataTypes.Http.Request.MainDoc" >}} +[SoapResponse]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapResponse.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[SoapMessage]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapMessage.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[HttpRequestVersion]: {{< url path="Cortex.Reference.DataTypes.Http.HttpRequestVersion.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/http/soap/soapresponse.md b/content/en/docs/2024.9/Reference/data-types/http/soap/soapresponse.md new file mode 100644 index 000000000..ca10bf182 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/http/soap/soapresponse.md @@ -0,0 +1,120 @@ +--- +title: "SoapResponse" +linkTitle: "SoapResponse" +description: "Used to represent a SOAP response." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Http.Soap.SoapResponse)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `SoapResponse` data type is used to represent a SOAP response. + +| | | +|-|-| +| **Category:** | Http | +| **Name:** | `SoapResponse` | +| **Full Name:** | `Cortex.DataTypes.Http.Soap.SoapResponse` | +| **Alias:** | N/A | +| **Description:** | Used to represent a SOAP response. | +| **Default Value:** | `null` | +| **Can be used as:** | `SoapResponse`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ResponseEnvelope + +The ResponseEnvelope is used to represent the content of the SOAP response. + +| | | +|--------------------|---------------------------| +| Data Type | [dynamic][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String] with value `$@""` | + +### ErrorMessage + +The ErrorMessage is used represent any errors that occurred when executing the SOAP request. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String] with value `$@""` | + +### Headers + +The Headers are used to represent the HTTP headers returned in the SOAP response. + +| | | +|--------------------|---------------------------| +| Data Type | [IDictionary][IDictionary] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IDictionary][IDictionary] with no value | + +### StatusCode + +The StatusCode is the status returned in the SOAP response. + +| | | +|--------------------|---------------------------| +| Data Type | [HttpStatusCode][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `OK` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SoapResponse`. +- The Literal Editor is available for [Input][] properties where the data type is `SoapResponse`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SoapResponse`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [dynamic][] +- [IDictionary][IDictionary] +- [HttpStatusCode][] +- [String][] +- [SoapRequest][] + +### Related Concepts + +None + +### External Documentation + +- [System.Net.HttpStatusCode][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[SoapRequest]: {{< url path = "Cortex.Reference.DataTypes.Http.Soap.SoapRequest.MainDoc" >}} + +[dynamic]: {{< url path="Cortex.Reference.DataTypes.All.dynamic.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[IDictionary]: {{< url path="Cortex.Reference.DataTypes.Collections.IDictionary.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[System.Net.HttpStatusCode]: {{< url path="MSDocs.DotNet.Api.System.Net.HttpStatusCode" >}} +[HttpStatusCode]: {{< url path = "Cortex.Reference.DataTypes.Http.HttpStatusCode.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/json/_index.md b/content/en/docs/2024.9/Reference/data-types/json/_index.md new file mode 100644 index 000000000..65d31a82a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/json/_index.md @@ -0,0 +1,6 @@ +--- +title: "Json" +linkTitle: "Json" +description: "Data types used for working with Json." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/json/jsonserializersettings.md b/content/en/docs/2024.9/Reference/data-types/json/jsonserializersettings.md new file mode 100644 index 000000000..b09620dd5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/json/jsonserializersettings.md @@ -0,0 +1,35 @@ +--- +title: "JsonSerializerSettings" +linkTitle: "JsonSerializerSettings" +description: "Used to specify settings for converting objects to and from Json." +--- + +# {{% param title %}} + +

(Newtonsoft.Json.JsonSerializerSettings)

+ +{{< workinprogress >}} + +## Summary + +## Remarks + +### Create a JsonSerializerSettings + +### Convert JsonSerializerSettings to Text + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation + +TODO: + +* Need to have a link to default settings and explain that convert object to json sets formatting.indented diff --git a/content/en/docs/2024.9/Reference/data-types/logs/_index.md b/content/en/docs/2024.9/Reference/data-types/logs/_index.md new file mode 100644 index 000000000..f8a87a45b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/logs/_index.md @@ -0,0 +1,6 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: "Data types used for working with logs." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/logs/eventseverity.md b/content/en/docs/2024.9/Reference/data-types/logs/eventseverity.md new file mode 100644 index 000000000..8c0f9bcb0 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/logs/eventseverity.md @@ -0,0 +1,72 @@ +--- +title: "EventSeverity" +linkTitle: "EventSeverity" +description: "Used to represent the severity of an event when it is logged." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Logs.EventSeverity)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `EventSeverity` data type is used to represent the severity of an event when it is logged. + +`EventSeverity` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Logs | +| **Name:** | `EventSeverity` | +| **Full Name:** | `Cortex.DataTypes.Logs.EventSeverity` | +| **Alias:** | N/A | +| **Description:** | Used to represent the severity of an event when it is logged. | +| **Default Value:** | `(EventSeverity)0` | +| **Can be used as:** | `EventSeverity`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)EventSeverity.Verbose` or `(System.Int16)EventSeverity.Verbose` or `(short)EventSeverity.Verbose`) | +| | `Int32` (e.g. `(Int32)EventSeverity.Verbose` or `(System.Int32)EventSeverity.Verbose` or `(int)EventSeverity.Verbose`) | +| | `Int64` (e.g. `(Int64)EventSeverity.Verbose` or `(System.Int64)EventSeverity.Verbose` or `(long)EventSeverity.Verbose`) | +| | `Single` (e.g. `(Single)EventSeverity.Verbose` or `(System.Single)EventSeverity.Verbose` or `(float)EventSeverity.Verbose`) | +| | `Double` (e.g. `(Double)EventSeverity.Verbose` or `(System.Double)EventSeverity.Verbose` or `(double)EventSeverity.Verbose`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EventSeverity`. +- The Literal Editor is available for [Input][] properties where the data type is `EventSeverity`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EventSeverity`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/loops/_index.md b/content/en/docs/2024.9/Reference/data-types/loops/_index.md new file mode 100644 index 000000000..726dfb583 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/loops/_index.md @@ -0,0 +1,6 @@ +--- +title: "Loops" +linkTitle: "Loops" +description: "Data types used for working with loops." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/loops/infinitelooperrorcode.md b/content/en/docs/2024.9/Reference/data-types/loops/infinitelooperrorcode.md new file mode 100644 index 000000000..d6c34bec4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/loops/infinitelooperrorcode.md @@ -0,0 +1,77 @@ +--- +title: "InfiniteLoopErrorCode" +linkTitle: "InfiniteLoopErrorCode" +description: "Used to represent an error code explaining the reason an `InfiniteLoopException` occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Loops.InfiniteLoopErrorCode)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `InfiniteLoopErrorCode` data type is used to represent an error code explaining the reason an [InfiniteLoopException][] occurred. For more information on the exception itself, see [InfiniteLoopException][]. + +`InfiniteLoopErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Loops | +| **Name:** | `InfiniteLoopErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Loops.InfiniteLoopErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason an [InfiniteLoopException][] occurred. | +| **Default Value:** | `(InfiniteLoopErrorCode)0` | +| **Can be used as:** | `InfiniteLoopErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)InfiniteLoopErrorCode.IncrementIsZero` or `(System.Int16)InfiniteLoopErrorCode.IncrementIsZero` or `(short)InfiniteLoopErrorCode.IncrementIsZero`) | +| | `Int32` (e.g. `(Int32)InfiniteLoopErrorCode.IncrementIsZero` or `(System.Int32)InfiniteLoopErrorCode.IncrementIsZero` or `(int)InfiniteLoopErrorCode.IncrementIsZero`) | +| | `Int64` (e.g. `(Int64)InfiniteLoopErrorCode.IncrementIsZero` or `(System.Int64)InfiniteLoopErrorCode.IncrementIsZero` or `(long)InfiniteLoopErrorCode.IncrementIsZero`) | +| | `Single` (e.g. `(Single)InfiniteLoopErrorCode.IncrementIsZero` or `(System.Single)InfiniteLoopErrorCode.IncrementIsZero` or `(float)InfiniteLoopErrorCode.IncrementIsZero`) | +| | `Double` (e.g. `(Double)InfiniteLoopErrorCode.IncrementIsZero` or `(System.Double)InfiniteLoopErrorCode.IncrementIsZero` or `(double)InfiniteLoopErrorCode.IncrementIsZero`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `InfiniteLoopErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `InfiniteLoopErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `InfiniteLoopErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [InfiniteLoopException][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working with Loops][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Working with Loops]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Loops.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[InfiniteLoopException]: {{< url path = "Cortex.Reference.Exceptions.Loops.InfiniteLoopException.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/_index.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/_index.md new file mode 100644 index 000000000..cda4ff1ea --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/_index.md @@ -0,0 +1,6 @@ +--- +title: "Microsoft 365" +linkTitle: "Microsoft 365" +description: "Data types used for working with Microsoft 365 blocks." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/_index.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/_index.md new file mode 100644 index 000000000..a6aa855da --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/_index.md @@ -0,0 +1,6 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Data types used for authentication when working with Microsoft 365 blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/_index.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/_index.md new file mode 100644 index 000000000..4e0da8906 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/_index.md @@ -0,0 +1,6 @@ +--- +title: "OAuth" +linkTitle: "OAuth" +description: "Data types used for authentication via OAuth when working with Microsoft 365 blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365credentials.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365credentials.md new file mode 100644 index 000000000..2ad3f9a46 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365credentials.md @@ -0,0 +1,63 @@ +--- +title: "Microsoft365Credentials" +linkTitle: "Microsoft365Credentials" +description: "Any data type used to represent details required when establishing a connection with a mail server hosted by Outlook." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required when establishing a connection with a mail server hosted by Outlook. + +| | | +|-|-| +| **Category:** | Microsoft365 | +| **Name:** | `Microsoft365Credentials` | +| **Full Name:** | `Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required when establishing a connection with a mail server hosted by Outlook. | +| **Default Value:** | null | +| **Can be used as:** | `Microsoft365Credentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Microsoft365Credentials`. +- The Literal Editor is available for [Input][] properties where the data type is `Microsoft365Credentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Microsoft365Credentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Microsoft365OAuthCertificateCredentials][] +- [Microsoft365OAuthCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Microsoft365OAuthCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.MainDoc" >}} +[Microsoft365OAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcertificatecredentials.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcertificatecredentials.md new file mode 100644 index 000000000..b6a123ee6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcertificatecredentials.md @@ -0,0 +1,129 @@ +--- +title: "Microsoft365OAuthCertificateCredentials" +linkTitle: "Microsoft365OAuthCertificateCredentials" +description: "Used to represent public key credentials required to authenticate, via OAuth, with a server hosted by Outlook." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `Microsoft365OAuthCertificateCredentials` data type is used to represent public key credentials required to authenticate, via OAuth, with a server hosted by Outlook. + +| | | +|-|-| +| **Category:** | Microsoft365 | +| **Name:** | `Microsoft365OAuthCertificateCredentials` | +| **Full Name:** | `Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent public key credentials required to authenticate, via OAuth, with a server hosted by Outlook. | +| **Default Value:** | null | +| **Can be used as:** | `Microsoft365OAuthCertificateCredentials`, `Microsoft365Credentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### CertificatePath + +The CertificatePath is used to define the path pointing to the X.509 certificate file to be used for authentication via OAuth, the certificate file must be accessible from the server executing the flow. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `$@""` | + +### CertificatePassword + +The CertificatePassword is used to define the password associated with the certificate file at the [CertificatePath][]. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +### ClientId + +The ClientId is used to define the client ID of the client application created to allow authentication via OAuth. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### TenantId + +The TenantId is used to define the Microsoft365 tenant in which the client application is registered. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### ObjectId + +The ObjectId of the user who is authenticating. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Microsoft365OAuthCertificateCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `Microsoft365OAuthCertificateCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Microsoft365OAuthCertificateCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [EncryptedText][] +- [Microsoft365Credentials][] +- [Microsoft365OAuthCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[CertificatePath]: {{< ref "#certificatepath">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[Microsoft365Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials.MainDoc" >}} +[Microsoft365OAuthCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcredentials.md b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcredentials.md new file mode 100644 index 000000000..d4f489e63 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/microsoft365/authentication/oauth/microsoft365oauthcredentials.md @@ -0,0 +1,115 @@ +--- +title: "Microsoft365OAuthCredentials" +linkTitle: "Microsoft365OAuthCredentials" +description: "Used to represent client credentials required to authenticate, via OAuth, with a server hosted by Outlook." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `Microsoft365OAuthCredentials` data type is used to represent client credentials required to authenticate, via OAuth, with a server hosted by Outlook. + +| | | +|-|-| +| **Category:** | Microsoft365 | +| **Name:** | `Microsoft365OAuthCredentials` | +| **Full Name:** | `Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent client credentials required to authenticate, via OAuth, with a server hosted by Outlook. | +| **Default Value:** | null | +| **Can be used as:** | `Microsoft365OAuthCredentials`, `Microsoft365Credentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ClientId + +The ClientId is used to define the client ID of the client application created to allow authentication via OAuth. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### ClientSecret + +The ClientSecret is used to define the secret used to authenticate with the client application, this value should be kept secret. This property is an [EncryptedText][] and so it must be encrypted; for more information on how to encrypt the password, see [EncryptedText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptedText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptedText][] with value `""` | + +### TenantId + +The TenantId is used to define the Microsoft365 tenant in which the client application is registered. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### ObjectId + +The ObjectId of the user who is authenticating. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Microsoft365OAuthCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `Microsoft365OAuthCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Microsoft365OAuthCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [EncryptedText][] +- [Microsoft365Credentials][] +- [Microsoft365OAuthCertificateCredentials][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[Microsoft365Credentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials.MainDoc" >}} +[Microsoft365OAuthCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/most-common/_index.md b/content/en/docs/2024.9/Reference/data-types/most-common/_index.md new file mode 100644 index 000000000..2a153650b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/most-common/_index.md @@ -0,0 +1,16 @@ +--- +title: "Most Common" +linkTitle: "Most Common" +description: "Data types that are most commonly used." +weight: 3 +--- + +## Data Types + +### Lists + +### Dictionaries + +### InvariantCulture + +### HttpRequestHeaders diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/_index.md b/content/en/docs/2024.9/Reference/data-types/numbers/_index.md new file mode 100644 index 000000000..a0551f735 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/_index.md @@ -0,0 +1,6 @@ +--- +title: "Numbers" +linkTitle: "Numbers" +description: "Data types used for working with numbers." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/double.md b/content/en/docs/2024.9/Reference/data-types/numbers/double.md new file mode 100644 index 000000000..f4e13571b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/double.md @@ -0,0 +1,112 @@ +--- +title: "Double" +linkTitle: "Double" +description: "Used to represent a fractional, or very large or small number from `-1.79769313486232e+308` through `1.79769313486232e+308`." +--- + +# {{% param title %}} + +

(System.Double)

+ +## Summary + +The `Double` data type is used to represent a fractional, or very large or small number from `-1.79769313486232e+308` through `1.79769313486232e+308`. + +| | | +|-|-| +| **Category:** | Numbers | +| **Name:** | `Double` | +| **Full Name:** | `System.Double` | +| **Alias:** | `double` | +| **Description:** | A fractional, or very large or small number from `-1.79769313486232e+308` through `1.79769313486232e+308` | +| **Size:** | `8` bytes | +| **Default Value:** | `0` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | `Int16`, as long as value is from `-32,768` through `32,767` (e.g. `(Int16)32767` or `(System.Int16)32767` or `(short)32767`) | +| | `Int32`, as long as value is from `-2,147,483,648` through `2,147,483,647` (e.g. `(Int32)2147483647` or `(System.Int32)2147483647` or `(int)2147483647`) | +| | `Int64`, as long as value is from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807` (e.g. `(Int64)9223372036854775807` or `(System.Int64)9223372036854775807` or `(long)9223372036854775807`) | +| | `Single`, as long as value is from `-3.402823e+38` through `3.402823e+38` (e.g. `(Single)3.402823e+38` or `(System.Single)3.402823e+38` or `(float)3.402823e+38`) | + +## Remarks + +### Create a Double + +The following table shows some of the ways that a `Double` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `Double` literal | `0.0` | `0.0` | Literal, Expression | Zero | +| | `1.0` | `1.0` | Literal, Expression | Positive | +| | `-1.0` | `-1.0` | Literal, Expression | Negative | +| Use a `Double` expression | `1.0 + 1.0` | `2.0` | Expression | Add | +| | `1.0 - 1.0` | `0.0` | Expression | Subtract | +| | `1.0 * 1.0` | `1.0` | Expression | Multiply | +| | `1.0 / 1.0` | `1.0` | Expression | Divide | +| | `Double.MaxValue` | `1.79769313486232e+308` | Expression | Maximum value of a `Double`. See [Double.MaxValue][] | +| | `Double.MinValue` | `-1.79769313486232e+308` | Expression | Minimum value of a `Double`. See [Double.MinValue][] | +| | `Double.Parse("1")` | `1.0` | Expression | Attempts to parse text and convert it to a `Double` value. See [Double.Parse][] | +| | `Convert.ToDouble("1")` | `1.0` | Expression | Attempts to convert text to a `Double` value. See [Convert.ToDouble][] | + +### Convert Double to Text + +The following table shows some of the ways that a `Double` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `1.0.ToString()` | `"1"` | Expression | See [Double.ToString][] | +| | `($)DoubleVariable.ToString()` where `($)DoubleVariable` has a `Double` value of `1.0` | `"1"` | Expression | See [Double.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(1.0)` | `"1"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)DoubleVariable)` where `($)DoubleVariable` has a `Double` value of `1.0` | `"1"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a `Double` value of `1.0` | `"1"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a `Double` value of `1.0` | `"1.0"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Double`. +* The Literal Editor is available for [Input][] properties where the data type is `Double`. + * Expression syntax is not supported within the Literal Editor for the `Double` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Double`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int16][] +* [Int32][] +* [Int64][] +* [Single][] + +### Related Concepts + +* [Working with Numbers][] + +### External Documentation + +* [System.Double][] + +[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" >}} + +[Convert.ToDouble]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToDouble" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Double]: {{< url path="MSDocs.DotNet.Api.System.Double.MainDoc" >}} +[Double.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Double.MaxValue" >}} +[Double.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Double.MinValue" >}} +[Double.Parse]: {{< url path="MSDocs.DotNet.Api.System.Double.Parse" >}} +[Double.ToString]: {{< url path="MSDocs.DotNet.Api.System.Double.ToString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} + +[Working with Numbers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Numbers.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/int16.md b/content/en/docs/2024.9/Reference/data-types/numbers/int16.md new file mode 100644 index 000000000..b58e15146 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/int16.md @@ -0,0 +1,106 @@ +--- +title: "Int16" +linkTitle: "Int16" +description: "Used to represent a whole number from `-32,768` through `32767`." +--- + +# {{% param title %}} + +

(System.Int16)

+ +## Summary + +The `Int16` data type is used to represent a whole number from `-32,768` through `32,767`. + +| | | +|-|-| +| **Category:** | Numbers | +| **Name:** | `Int16` | +| **Full Name:** | `System.Int16` | +| **Alias:** | `short` | +| **Description:** | A whole number from `-32,768` through `32,767` | +| **Size:** | `2` bytes | +| **Default Value:** | `0` | +| **Can be used as:** | `Int16`, `Int32`, `Int64`, `Single`, `Double`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Create an Int16 + +The following table shows some of the ways that an `Int16` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `Int16` expression | `(Int16)(1 + 1)` | `2` | Expression | Add | +| | `(System.Int16)(1 - 1)` | `0` | Expression | Subtract | +| | `(short)(1 * 1)` | `1` | Expression | Multiply | +| | `(short)(1 / 1)` | `1` | Expression | Divide | +| | `Int16.MaxValue` | `32767` | Expression | Maximum value of an `Int16`. See [Int16.MaxValue][] | +| | `Int16.MinValue` | `-32768` | Expression | Minimum value of an `Int16`. See [Int16.MinValue][] | +| | `Int16.Parse("1")` | `1` | Expression | Attempts to parse text and convert it to an `Int16` value. See [Int16.Parse][] | +| | `Convert.ToInt16("1")` | `1` | Expression | Attempts to convert text to an `Int16` value. See [Convert.ToInt16][] | + +### Convert Int16 to Text + +The following table shows some of the ways that an `Int16` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `((Int16)1).ToString()` | `"1"` | Expression | See [Int16.ToString][] | +| | `($)Int16Variable.ToString()` where `($)Int16Variable` has an `Int16` value of `1` | `"1"` | Expression | See [Int16.ToString][] | +| Use `Convert.ToString` | `Convert.ToString((Int16)1)` | `"1"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)Int16Variable)` where `($)Int16Variable` has an `Int16` value of `1` | `"1"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has an `Int16` value of `1` | `"1"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has an `Int16` value of `1` | `"1"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Int16`. +* The Literal Editor is available for [Input][] properties where the data type is `Int16`. + * Expression syntax is not supported within the Literal Editor for the `Int16` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Int16`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int32][] +* [Int64][] +* [Single][] +* [Double][] + +### Related Concepts + +* [Working with Numbers][] + +### External Documentation + +* [System.Int16][] + +[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" >}} + +[Convert.ToInt16]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt16" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Int16]: {{< url path="MSDocs.DotNet.Api.System.Int16.MainDoc" >}} +[Int16.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Int16.MaxValue" >}} +[Int16.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Int16.MinValue" >}} +[Int16.Parse]: {{< url path="MSDocs.DotNet.Api.System.Int16.Parse" >}} +[Int16.ToString]: {{< url path="MSDocs.DotNet.Api.System.Int16.ToString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} + +[Working with Numbers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Numbers.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/int32.md b/content/en/docs/2024.9/Reference/data-types/numbers/int32.md new file mode 100644 index 000000000..cba70cae8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/int32.md @@ -0,0 +1,115 @@ +--- +title: "Int32" +linkTitle: "Int32" +description: "Used to represent a whole number from `-2,147,483,648` through `2,147,483,647`." +--- + +# {{% param title %}} + +

(System.Int32)

+ +## Summary + +The `Int32` data type is used to represent a whole number from `-2,147,483,648` through `2,147,483,647`. + +| | | +|-|-| +| **Category:** | Numbers | +| **Name:** | `Int32` | +| **Full Name:** | `System.Int32` | +| **Alias:** | `int` | +| **Description:** | A whole number from `-2,147,483,648` through `2,147,483,647` | +| **Size:** | `4` bytes | +| **Default Value:** | `0` | +| **Can be used as:** | `Int32`, `Int64`, `Single`, `Double`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16`, as long as value is from `-32,768` through `32,767` (e.g. `(Int16)32767` or `(System.Int16)32767` or `(short)32767`) | + +## Remarks + +### Create an Int32 + +The following table shows some of the ways that an `Int32` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare an `Int32` literal | `0` | `0` | Literal, Expression | Zero | +| | `1` | `1` | Literal, Expression | Positive | +| | `-1` | `-1` | Literal, Expression | Negative | +| Use an `Int32` expression | `1 + 1` | `2` | Expression | Add | +| | `1 - 1` | `0` | Expression | Subtract | +| | `1 * 1` | `1` | Expression | Multiply | +| | `1 / 1` | `1` | Expression | Divide | +| | `Int32.MaxValue` | `2147483647` | Expression | Maximum value of an `Int32`. See [Int32.MaxValue][] | +| | `Int32.MinValue` | `-2147483648` | Expression | Minimum value of an `Int32`. See [Int32.MinValue][] | +| | `Int32.Parse("1")` | `1` | Expression | Attempts to parse text and convert it to an `Int32` value. See [Int32.Parse][] | +| | `Convert.ToInt32("1")` | `1` | Expression | Attempts to convert text to an `Int32` value. See [Convert.ToInt32][] | + +Please see [Instantiating an Int32 Value][] for further information. + +### Convert Int32 to Text + +The following table shows some of the ways that an `Int32` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `1.ToString()` | `"1"` | Expression | See [Int32.ToString][] | +| | `($)Int32Variable.ToString()` where `($)Int32Variable` has a value of `1` | `"1"` | Expression | See [Int32.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(1)` | `"1"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)Int32Variable)` where `($)Int32Variable` has a value of `1` | `"1"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `1` | `"1"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `1` | `"1"` | N/A | See [Convert Object To Json][] | + +Please see [Representing an Int32 as a String][] for further information. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Int32`. +* The Literal Editor is available for [Input][] properties where the data type is `Int32`. + * Expression syntax is not supported within the Literal Editor for the `Int32` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Int32`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int16][] +* [Int64][] +* [Single][] +* [Double][] + +### Related Concepts + +* [Working with Numbers][] + +### External Documentation + +* [System.Int32][] + +[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" >}} + +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Int32]: {{< url path="MSDocs.DotNet.Api.System.Int32.MainDoc" >}} +[Int32.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Int32.MaxValue" >}} +[Int32.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Int32.MinValue" >}} +[Int32.Parse]: {{< url path="MSDocs.DotNet.Api.System.Int32.Parse" >}} +[Int32.ToString]: {{< url path="MSDocs.DotNet.Api.System.Int32.ToString" >}} +[Instantiating an Int32 Value]: {{< url path="MSDocs.DotNet.Api.System.Int32.InstantiatingAnInt32" >}} +[Representing an Int32 as a String]: {{< url path="MSDocs.DotNet.Api.System.Int32.RepresentingAnInt32AsAString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} + +[Working with Numbers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Numbers.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/int64.md b/content/en/docs/2024.9/Reference/data-types/numbers/int64.md new file mode 100644 index 000000000..0d436a65d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/int64.md @@ -0,0 +1,115 @@ +--- +title: "Int64" +linkTitle: "Int64" +description: "Used to represent a whole number from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807`." +--- + +# {{% param title %}} + +

(System.Int64)

+ +## Summary + +The `Int64` data type is used to represent a whole number from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807`. + +| | | +|-|-| +| **Category:** | Numbers | +| **Name:** | `Int64` | +| **Full Name:** | `System.Int64` | +| **Alias:** | `long` | +| **Description:** | A whole number from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807` | +| **Size:** | `8` bytes | +| **Default Value:** | `0` | +| **Can be used as:** | `Int64`, `Single`, `Double`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16`, as long as value is from `-32,768` through `32,767` (e.g. `(Int16)32767` or `(System.Int16)32767` or `(short)32767`) | +| | `Int32`, as long as value is from `-2,147,483,648` through `2,147,483,647` (e.g. `(Int32)2147483647` or `(System.Int32)2147483647` or `(int)2147483647`) + +## Remarks + +### Create an Int64 + +The following table shows some of the ways that an `Int64` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare an `Int64` literal | `9223372036854775807` | `9223372036854775807` | Literal, Expression | Positive, where value is greater than `2,147,483,647`. If it is between `0` and `2,147,483,647` it will only be an `Int64` if the property's data type is also `Int64`, otherwise it will be an `Int32`. | +| | `-9223372036854775808` | `-9223372036854775808` | Literal, Expression | Negative, where value is less than `-2,147,483,648`. If it is between `-2,147,483,648` and `0` it will only be an `Int64` if the property's data type is also `Int64`, otherwise it will be an `Int32`. | +| Use an `Int64` expression | `(Int64)(1 + 1)` | `2` | Expression | Add | +| | `(System.Int64)(1 - 1)` | `0` | Expression | Subtract | +| | `(long)(1 * 1)` | `1` | Expression | Multiply | +| | `(long)(1 / 1)` | `1` | Expression | Divide | +| | `Int64.MaxValue` | `9223372036854775807` | Expression | Maximum value of an `Int64`. See [Int64.MaxValue][] | +| | `Int64.MinValue` | `-9223372036854775808` | Expression | Minimum value of an `Int64`. See [Int64.MinValue][] | +| | `Int64.Parse("1")` | `1` | Expression | Attempts to parse text and convert it to an `Int64` value. See [Int64.Parse][] | +| | `Convert.ToInt64("1")` | `1` | Expression | Attempts to convert text to an `Int64` value. See [Convert.ToInt64][] | + +Please see [Instantiating an Int64 Value][] for further information. + +### Convert Int64 to Text + +The following table shows some of the ways that an `Int64` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `((Int64)1).ToString()` | `"1"` | Expression | See [Int64.ToString][] | +| | `($)Int64Variable.ToString()` where `($)Int64Variable` has an `Int64` value of `1` | `"1"` | Expression | See [Int64.ToString][] | +| Use `Convert.ToString` | `Convert.ToString((Int64)1)` | `"1"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)Int64Variable)` where `($)Int64Variable` has an `Int64` value of `1` | `"1"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has an `Int64` value of `1` | `"1"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has an `Int64` value of `1` | `"1"` | N/A | See [Convert Object To Json][] | + +Please see [Representing an Int64 as a String][] for further information. + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Int64`. +* The Literal Editor is available for [Input][] properties where the data type is `Int64`. + * Expression syntax is not supported within the Literal Editor for the `Int64` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Int64`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int16][] +* [Int32][] +* [Single][] +* [Double][] + +### Related Concepts + +* [Working with Numbers][] + +### External Documentation + +* [System.Int64][] + +[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" >}} + +[Convert.ToInt64]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt64" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Int64]: {{< url path="MSDocs.DotNet.Api.System.Int64.MainDoc" >}} +[Int64.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Int64.MaxValue" >}} +[Int64.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Int64.MinValue" >}} +[Int64.Parse]: {{< url path="MSDocs.DotNet.Api.System.Int64.Parse" >}} +[Int64.ToString]: {{< url path="MSDocs.DotNet.Api.System.Int64.ToString" >}} +[Instantiating an Int64 Value]: {{< url path="MSDocs.DotNet.Api.System.Int64.InstantiatingAnInt64" >}} +[Representing an Int64 as a String]: {{< url path="MSDocs.DotNet.Api.System.Int64.RepresentingAnInt64AsAString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Single]: {{< url path="Cortex.Reference.DataTypes.Numbers.Single.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} + +[Working with Numbers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Numbers.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/numbers/single.md b/content/en/docs/2024.9/Reference/data-types/numbers/single.md new file mode 100644 index 000000000..216b69523 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/numbers/single.md @@ -0,0 +1,108 @@ +--- +title: "Single" +linkTitle: "Single" +description: "Used to represent a fractional, or very large or small number from `-3.402823e+38` through `3.402823e+38`." +--- + +# {{% param title %}} + +

(System.Single)

+ +## Summary + +The `Single` data type is used to represent a fractional, or very large or small number from `-3.402823e+38` through `3.402823e+38`. + +| | | +|-|-| +| **Category:** | Numbers | +| **Name:** | `Single` | +| **Full Name:** | `System.Single` | +| **Alias:** | `float` | +| **Description:** | A fractional, or very large or small number from `-3.402823e+38` through `3.402823e+38` | +| **Size:** | `4` bytes | +| **Default Value:** | `0` | +| **Can be used as:** | `Double`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16`, as long as value is from `-32,768` through `32,767` (e.g. `(Int16)32767` or `(System.Int16)32767` or `(short)32767`) | +| | `Int32`, as long as value is from `-2,147,483,648` through `2,147,483,647` (e.g. `(Int32)2147483647` or `(System.Int32)2147483647` or `(int)2147483647`) | +| | `Int64`, as long as value is from `-9,223,372,036,854,775,808` through `9,223,372,036,854,775,807` (e.g. `(Int64)9223372036854775807` or `(System.Int64)9223372036854775807` or `(long)9223372036854775807`) | + +## Remarks + +### Create a Single + +The following table shows some of the ways that a `Single` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Single` expression | `1.0f + 1.0f` | `2.0` | Expression | Add | +| | `1.0f - 1.0f` | `0.0` | Expression | Subtract | +| | `1.0f * 1.0f` | `1.0` | Expression | Multiply | +| | `1.0f / 1.0f` | `1.0` | Expression | Divide | +| | `Single.MaxValue` | `3.402823e+38` | Expression | Maximum value of a `Single`. See [Single.MaxValue][] | +| | `Single.MinValue` | `-3.402823e+38` | Expression | Minimum value of a `Single`. See [Single.MinValue][] | +| | `Single.Parse("1")` | `1.0` | Expression | Attempts to parse text and convert it to a `Single` value. See [Single.Parse][] | +| | `Convert.ToSingle("1")` | `1.0` | Expression | Attempts to convert text to a `Single` value. See [Convert.ToSingle][] | + +### Convert Single to Text + +The following table shows some of the ways that a `Single` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `1.0f.ToString()` | `"1"` | Expression | See [Single.ToString][] | +| | `($)SingleVariable.ToString()` where `($)SingleVariable` has a `Single` value of `1.0` | `"1"` | Expression | See [Single.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(1.0f)` | `"1"` | Expression | See [Convert.ToString][] | +| | `Convert.ToString(($)SingleVariable)` where `($)SingleVariable` has a `Single` value of `1.0` | `"1"` | Expression | See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a `Single` value of `1.0` | `"1"` | N/A | See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a `Single` value of `1.0` | `"1.0"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `Single`. +* The Literal Editor is available for [Input][] properties where the data type is `Single`. + * Expression syntax is not supported within the Literal Editor for the `Single` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `Single`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int16][] +* [Int32][] +* [Int64][] +* [Double][] + +### Related Concepts + +* [Working with Numbers][] + +### External Documentation + +* [System.Single][] + +[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" >}} + +[Convert.ToSingle]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToSingle" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[System.Single]: {{< url path="MSDocs.DotNet.Api.System.Single.MainDoc" >}} +[Single.MaxValue]: {{< url path="MSDocs.DotNet.Api.System.Single.MaxValue" >}} +[Single.MinValue]: {{< url path="MSDocs.DotNet.Api.System.Single.MinValue" >}} +[Single.Parse]: {{< url path="MSDocs.DotNet.Api.System.Single.Parse" >}} +[Single.ToString]: {{< url path="MSDocs.DotNet.Api.System.Single.ToString" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Int16]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int16.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Int64]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int64.MainDoc" >}} +[Double]: {{< url path="Cortex.Reference.DataTypes.Numbers.Double.MainDoc" >}} + +[Working with Numbers]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Numbers.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/other/_index.md b/content/en/docs/2024.9/Reference/data-types/other/_index.md new file mode 100644 index 000000000..814b484ba --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/other/_index.md @@ -0,0 +1,6 @@ +--- +title: "Other" +linkTitle: "Other" +description: "Data types that don't match other categories." +weight: 2 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/other/guid.md b/content/en/docs/2024.9/Reference/data-types/other/guid.md new file mode 100644 index 000000000..d9c55a77d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/other/guid.md @@ -0,0 +1,31 @@ +--- +title: "Guid" +linkTitle: "Guid" +description: "Used to represent a globally unique identifier (GUID)." +--- + +# {{% param title %}} + +

(System.Guid)

+ +{{< workinprogress >}} + +## Summary + +## Remarks + +### Create a Guid + +### Convert Guid to Text + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation diff --git a/content/en/docs/2024.9/Reference/data-types/other/nullable-1.md b/content/en/docs/2024.9/Reference/data-types/other/nullable-1.md new file mode 100644 index 000000000..4099f5fd1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/other/nullable-1.md @@ -0,0 +1,31 @@ +--- +title: "Nullable" +linkTitle: "Nullable" +description: "Used to represent a value type that can be set to `null`." +--- + +# {{% param title %}} + +

(System.Nullable<T>)

+ +{{< workinprogress >}} + +## Summary + +## Remarks + +### Create a Nullable<T> + +### Convert Nullable<T> to Text + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation diff --git a/content/en/docs/2024.9/Reference/data-types/powershell/_index.md b/content/en/docs/2024.9/Reference/data-types/powershell/_index.md new file mode 100644 index 000000000..a4649eb72 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/powershell/_index.md @@ -0,0 +1,6 @@ +--- +title: "PowerShell" +linkTitle: "PowerShell" +description: "Data types used for working with PowerShell." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/powershell/powershellsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/powershell/powershellsessiondetails.md new file mode 100644 index 000000000..95999455f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/powershell/powershellsessiondetails.md @@ -0,0 +1,142 @@ +--- +title: "PowerShellSessionDetails" +linkTitle: "PowerShellSessionDetails" +description: "Any data type representing configuration for executing PowerShell commands or scripts on a specified host." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.PowerShell.PowerShellSessionDetails)

+ +## Summary + +Any data type representing configuration for executing PowerShell commands or scripts on a specified host. + +| | | +|-|-| +| **Category:** | PowerShell | +| **Name:** | `PowerShellSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.PowerShell.PowerShellSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Any data type representing configuration for executing PowerShell commands or scripts on a specified host. | +| **Default Value:** | `null` | +| **Can be used as:** | `PowerShellSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ServerDetails + +The ServerDetails are used to configure the [Host][] and [Port][] to connect to and whether or not to [UseSsl][]. + +| | | +|--------------------|---------------------------| +| Data Type | [ServerDetails][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [ServerDetails][] with value shown below: | + +```json +{ + "Host": "localhost", + "Port": 5986, + "UseSsl": true +} +``` + +### Credentials + +The Credentials are used to configure the [Domain][], [Username][] and [Password][] used to connect to the host. + +| | | +|--------------------|---------------------------| +| Data Type | [UserCredentials][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [UserCredentials][] with value shown below: | + +```json +{ + "Domain": "", + "Username": "", + "Password": "" +} +``` + +### PsConfiguration + +The PsConfiguration controls the PowerShell configuration that will be used by the host. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `"Microsoft.PowerShell"`: | + +## Remarks + +### Most Common PowerShellSessionDetails Data Types + +Any of the following data types can be used where a `PowerShellSessionDetails` is required: + +* [PowerShellWinRmSessionDetails][] + +### Create a PowerShellSessionDetails + +For some of the ways that a `PowerShellSessionDetails` can be created, please see each of the `PowerShellSessionDetails` data types: + +* [PowerShellWinRmSessionDetails][] + +### Convert PowerShellSessionDetails to Text + +For some of the ways that a `PowerShellSessionDetails` can be converted to text, please see each of the `PowerShellSessionDetails` data types: + +* [PowerShellWinRmSessionDetails][] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `PowerShellSessionDetails`. +* The Literal Editor is available for [Input][] properties where the data type is `PowerShellSessionDetails`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `PowerShellSessionDetails`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +* [PowerShellWinRMSessionDetails][] +* [ServerDetails][] +* [String][] +* [UserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[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" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[PowerShellWinRMSessionDetails]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellWinRMSessionDetails.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/powershell/powershellwinrmsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/powershell/powershellwinrmsessiondetails.md new file mode 100644 index 000000000..8d3e80111 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/powershell/powershellwinrmsessiondetails.md @@ -0,0 +1,126 @@ +--- +title: "PowerShellWinRmSessionDetails" +linkTitle: "PowerShellWinRmSessionDetails" +description: "Used to represent configuration for executing PowerShell commands or scripts on a specified host, via WinRm." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.PowerShell.PowerShellWinRmSessionDetails)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `PowerShellWinRmSessionDetails` data type is used to represent configuration for executing PowerShell commands or scripts on a specified host, via WinRm. + +| | | +|-|-| +| **Category:** | PowerShell | +| **Name:** | `PowerShellWinRmSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.PowerShell.PowerShellWinRmSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Used to represent configuration for executing PowerShell commands or scripts on a specified host, via WinRm. | +| **Default Value:** | `null` | +| **Can be used as:** | `PowerShellWinRmSessionDetails`, `PowerShellSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ServerDetails + +The ServerDetails are used to configure the [Host][] and [Port][] to connect to and whether or not to [UseSsl][]. + +| | | +|--------------------|---------------------------| +| Data Type | [ServerDetails][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [ServerDetails][] with value shown below: | + +```json +{ + "Host": "", + "Port": 465, + "UseSsl": true +} +``` + +### Credentials + +The Credentials are used to configure the [Domain][], [Username][] and [Password][] used to connect to the host. + +| | | +|--------------------|---------------------------| +| Data Type | [UserCredentials][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [UserCredentials][] with value shown below: | + +```json +{ + "Domain": "", + "Username": "", + "Password": "" +} +``` + +### PsConfiguration + +The PsConfiguration controls the PowerShell configuration that will be used by the host. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `"Microsoft.PowerShell"`: | + +## Remarks + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `PowerShellWinRmSessionDetails`. +* The Literal Editor is available for [Input][] properties where the data type is `PowerShellWinRmSessionDetails`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `PowerShellWinRmSessionDetails`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +* [PowerShellSessionDetails][] +* [ServerDetails][] +* [String][] +* [UserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[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" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[PowerShellSessionDetails]: {{< url path="Cortex.Reference.DataTypes.PowerShell.PowerShellSessionDetails.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/powershell/psremotingerrorcode.md b/content/en/docs/2024.9/Reference/data-types/powershell/psremotingerrorcode.md new file mode 100644 index 000000000..60e9dcd3f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/powershell/psremotingerrorcode.md @@ -0,0 +1,75 @@ +--- +title: "PSRemotingErrorCode" +linkTitle: "PSRemotingErrorCode" +description: "Used to represent an error code explaining the reason a PSRemotingException occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.PowerShell.PSRemotingErrorCode)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `PSRemotingErrorCode` data type is used to represent an error code explaining the reason a [PSRemotingException][] occurred. For more information on the exception itself, see [PSRemotingException][]. + +`PSRemotingErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | PowerShell | +| **Name:** | `PSRemotingErrorCode` | +| **Full Name:** | `Cortex.DataTypes.PowerShell.PSRemotingErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [PSRemotingException][] occurred. | +| **Default Value:** | `(PSRemotingErrorCode)0` | +| **Can be used as:** | `PSRemotingErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)PSRemotingErrorCode.AccessDenied` or `(System.Int16)PSRemotingErrorCode.AccessDenied` or `(short)PSRemotingErrorCode.AccessDenied`) | +| | `Int32` (e.g. `(Int32)PSRemotingErrorCode.AccessDenied` or `(System.Int32)PSRemotingErrorCode.AccessDenied` or `(int)PSRemotingErrorCode.AccessDenied`) | +| | `Int64` (e.g. `(Int64)PSRemotingErrorCode.AccessDenied` or `(System.Int64)PSRemotingErrorCode.AccessDenied` or `(long)PSRemotingErrorCode.AccessDenied`) | +| | `Single` (e.g. `(Single)PSRemotingErrorCode.AccessDenied` or `(System.Single)PSRemotingErrorCode.AccessDenied` or `(float)PSRemotingErrorCode.AccessDenied`) | +| | `Double` (e.g. `(Double)PSRemotingErrorCode.AccessDenied` or `(System.Double)PSRemotingErrorCode.AccessDenied` or `(double)PSRemotingErrorCode.AccessDenied`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `PSRemotingErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `PSRemotingErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `PSRemotingErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] +- [PSRemotingException][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[PSRemotingException]: {{< url path = "Cortex.Reference.Exceptions.PowerShell.PSRemotingException.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/powershell/records.md b/content/en/docs/2024.9/Reference/data-types/powershell/records.md new file mode 100644 index 000000000..a565a24a6 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/powershell/records.md @@ -0,0 +1,145 @@ +--- +title: "Records" +linkTitle: "Records" +description: "Used to represent messages that are returned while executing a PowerShell command or script." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.PowerShell.Records)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `Records` data type is used to represent messages that are returned while executing a PowerShell command or script. + +Messages are categorised as: + +- [ErrorRecords][ErrorRecords] +- [WarningRecords][WarningRecords] +- [DebugRecords][DebugRecords] +- [ProgressRecords][ProgressRecords] +- [VerboseRecords][VerboseRecords] +- [InformationRecords][InformationRecords] + +| | | +|-|-| +| **Category:** | PowerShell| +| **Name:** | `Records` | +| **Full Name:** | `Cortex.DataTypes.PowerShell.Records` | +| **Alias:** | N/A | +| **Description:** | Used to represent messages that are returned while executing a PowerShell command or script. | +| **Default Value:** | null | +| **Can be used as:** | `Records`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ErrorRecords + +Represents the non-terminating errors that occurred when running a PowerShell command or script. +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +### WarningRecords + +Represents warning messages output when running a PowerShell command or script. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +### DebugRecords + +Represents debug messages output when running a PowerShell command or script. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +### ProgressRecords + +Represents the status of a PowerShell command or script at a point in time. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +### VerboseRecords + +Represents detailed or diagnostic information, output when running a PowerShell command or script. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +### InformationRecords + +Represents general information output when running a PowerShell command or script. + +| | | +|--------------------|---------------------------| +| Data Type | [IList][]<[String][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IList][]<[String][]> with no value | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Records`. +- The Literal Editor is available for [Input][] properties where the data type is `Records`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Records`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [String][] +- [IList][] + +### Related Concepts + +None + +### External Documentation + +None + +[ErrorRecords]: {{< ref "#errorrecords" >}} +[WarningRecords]: {{< ref "#warningrecords" >}} +[DebugRecords]: {{< ref "#debugrecords" >}} +[ProgressRecords]: {{< ref "#progressrecords" >}} +[VerboseRecords]: {{< ref "#verboserecords" >}} +[InformationRecords]: {{< ref "#informationrecords" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[IList]: {{< url path="Cortex.Reference.DataTypes.Collections.IList.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/scopes/_index.md b/content/en/docs/2024.9/Reference/data-types/scopes/_index.md new file mode 100644 index 000000000..1a065e28f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/scopes/_index.md @@ -0,0 +1,6 @@ +--- +title: "Scopes" +linkTitle: "Scopes" +description: "Data types used for working with Scopes." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/data-types/scopes/scope-definition.md b/content/en/docs/2024.9/Reference/data-types/scopes/scope-definition.md new file mode 100644 index 000000000..0940cbf2f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/scopes/scope-definition.md @@ -0,0 +1,152 @@ +--- +title: "ScopeDefinition" +linkTitle: "ScopeDefinition" +description: "Used to define the Scope in which an action takes place." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Scopes.ScopeDefinition)

+ +## Summary + +The `ScopeDefinition` data type is used to define the [Scope][] in which an action takes place. + +The `ScopeDefinition` is restricted by a number of levels: + +- [Tenant][Tenant Property] +- [System][System Property] +- [Package][Package Property] +- [Flow][Flow Property] + +Additional levels will be added in future releases, including: + +- Environment +- PackageVersion + +| | | +|---------------------|---------------------------------------------------------| +| **Category:** | Scopes | +| **Name:** | `ScopeDefinition` | +| **Full Name:** | `Cortex.DataTypes.Scopes.ScopeDefinition` | +| **Alias:** | N/A | +| **Description:** | Used to define the [Scope][] in which an action takes place. | +| **Default Value:** | `null` | +| **Can be used as:** | `ScopeDefinition`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Tenant + +The [Tenant][Tenant Property] is used to define the scope of the action at the tenant level. + +| | | +|-----------------|-----------------------| +| Data Type | [ScopeOption][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `ScopeOption.Current` | + +### System + +The [System][System Property] is used to define the scope of the action at the system level. + +| | | +|-----------------|-----------------------| +| Data Type | [ScopeOption][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `ScopeOption.Current` | + +### Package + +The [Package][Package Property] is used to define the scope of the action at the package level. + +| | | +|-----------------|-----------------------| +| Data Type | [ScopeOption][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `ScopeOption.Current` | + +### Flow + +The [Flow][Flow Property] is used to define the scope of the action at the flow level. + +| | | +|-----------------|-----------------------| +| Data Type | [ScopeOption][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `ScopeOption.All` | + +## Remarks + +### Create a Scope + +The following table shows some of the ways that `ScopeDefinition` can be created. + +| Method | Example | Result | Editor Support | Notes | +|---------------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------| +| Use a `ScopeDefinition` constructor | `new ScopeDefinition(tenant: ScopeOption.Current, system: ScopeOption.Current, package: ScopeOption.Current, flow: ScopeOption.All)` | `{"Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.Current", "Flow": "ScopeOption.All"}` | Expression | Creates a new `ScopeDefinition` that can be used to restrict an action to the current Tenant, System and Package, and any Flow. | + +A `ScopeDefinition` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-----------|---------------|-----------------------|-----------------------------------------------------------------------------------| +| `Tenant` | `ScopeOption` | `ScopeOption.Current` | [Tenant][Tenant Property] defines the scope of the action at the tenant level. | +| `System` | `ScopeOption` | `ScopeOption.Current` | [System][System Property] defines the scope of the action at the system level. | +| `Package` | `ScopeOption` | `ScopeOption.Current` | [Package][Package Property] defines the scope of the action at the package level. | +| `Flow` | `ScopeOption` | `ScopeOption.All` | [Flow][Flow Property] defines the scope of the action at the flow level. | + +### Convert Scope to Text + +The following table shows some of the ways that a `ScopeDefinition` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|------------------------------------|---------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|---------------------|--------------------------------| +| Use `Convert Object To Json` block | where `Object` property has a value of `{ "Tenant": "ScopeOption.Current", "System": "ScopeOption.Current", "Package": "ScopeOption.Current", "Flow": "ScopeOption.All" }` | `"{\r\n \"Tenant\": 1,\r\n \"System\": 1,\r\n \"Package\": 1,\r\n \"Flow\": 0\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ScopeDefinition`. +- The Literal Editor is available for [Input][] properties where the data type is `ScopeDefinition`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ScopeDefinition`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Scope][] +- [ScopeOption][] + +### Related Concepts + +- [Working with Scopes][] + +### External Documentation + +None + +[Tenant Property]: {{< ref "#tenant">}} +[System Property]: {{< ref "#system">}} +[Package Property]: {{< ref "#package">}} +[Flow Property]: {{< ref "#flow">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Scopes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Scopes.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} +[Scope]: {{< url path ="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/scopes/scope-option.md b/content/en/docs/2024.9/Reference/data-types/scopes/scope-option.md new file mode 100644 index 000000000..4b3bb78c1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/scopes/scope-option.md @@ -0,0 +1,138 @@ +--- +title: "ScopeOption" +linkTitle: "ScopeOption" +description: "Used to represent how each level of Scope is defined." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Scopes.ScopeOption)

+ +## Summary + +The `ScopeOption` data type is used to represent how each level of [ScopeDefinition] is defined. + +`ScopeOption` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Scopes | +| **Name:** | `ScopeOption` | +| **Full Name:** | `Cortex.DataTypes.Scopes.ScopeOption` | +| **Alias:** | N/A| +| **Description:** | The data type used to represent how each level of [ScopeDefinition] is defined. | +| **Default Value:** | `(ScopeOption)0` | +| **Can be used as:** | `ScopeOption`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)ScopeOption.Current` or `(System.Int16)ScopeOption.Current` or `(short)ScopeOption.Current`) | +| | `Int32` (e.g. `(Int32)ScopeOption.Current` or `(System.Int32)ScopeOption.Current` or `(int)ScopeOption.Current`) | +| | `Int64` (e.g. `(Int64)ScopeOption.Current` or `(System.Int64)ScopeOption.Current` or `(long)ScopeOption.Current`) | +| | `Single` (e.g. `(Single)ScopeOption.Current` or `(System.Single)ScopeOption.Current` or `(float)ScopeOption.Current`) | +| | `Double` (e.g. `(Double)ScopeOption.Current` or `(System.Double)ScopeOption.Current` or `(double)ScopeOption.Current`) | + +## Values + +### All + +| | | +|-|-| +| **Name:** | All | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Restricts a level within [ScopeDefinition] to a unique "All" value. | + +### Current + +| | | +|-|-| +| **Name:** | Current | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Restricts a level within [ScopeDefinition] to its current value (e.g. the current Tenant). | + +## Remarks + +### Create a ScopeOption + +The following table shows some of the ways that `ScopeOption` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `ScopeOption` literal | `Current` | `ScopeOption.Current`| Literal | Restricts a level within [ScopeDefinition] to its current value (e.g. the current Tenant). | +| Use a `ScopeOption` expression | `ScopeOption.Current` | `ScopeOption.Current` | Expression | Restricts a level within [ScopeDefinition] to its current value (e.g. the current Tenant). | +| Use [Explicit Casting][] | `(ScopeOption)1` | `ScopeOption.Current` | Expression | Restricts a level within [ScopeDefinition] to its current value (e.g. the current Tenant). | +| Use `Enum.Parse` | `(ScopeOption)Enum.Parse(typeof(ScopeOption), "Current")` | `ScopeOption.Current` | Expression | Parses `"Current"` and converts it to `ScopeOption.Current`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(ScopeOption)Enum.ToObject(typeof(ScopeOption), 1)` | `ScopeOption.Current`| Expression | Converts `1` to `ScopeOption.Current` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert ScopeOption to Text + +The following table shows some of the ways that a `ScopeOption` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `ScopeOption.Current.ToString()` | `"Current"` | Expression | Converts `ScopeOption.Current` to `"Current"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(ScopeOption.Current)` | `"Current"` | Expression | Converts `ScopeOption.Current` to `"Current"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `ScopeOption.Current` | `"Current"` | N/A | Converts `ScopeOption.Current` to `"Current"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `ScopeOption.Current` | `"1"` | N/A | Converts `ScopeOption.Current` to `"1"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert ScopeOption to a Number + +The following table shows some of the ways that a `ScopeOption` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)ScopeOption.Current` | `1` | Expression | [Casts][Explicit Casting] `ScopeOption.Current` to `1` | +| Use `Convert.ToInt32` | `Convert.ToInt32(ScopeOption.Current)` | `1` | Expression | Converts `ScopeOption.Current` to `1`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ScopeOption`. +- The Literal Editor is available for [Input][] properties where the data type is `ScopeOption`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ScopeOption`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ScopeDefinition][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working with Scopes][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Working with Scopes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Scopes.MainDoc">}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[ScopeDefinition]: {{< url path = "Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[ScopeOption]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeOption.MainDoc">}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/scopes/scope.md b/content/en/docs/2024.9/Reference/data-types/scopes/scope.md new file mode 100644 index 000000000..9371d08db --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/scopes/scope.md @@ -0,0 +1,131 @@ +--- +title: "Scope" +linkTitle: "Scope" +description: "Represents the Scope defined by a ScopeDefinition." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Scopes.Scope)

+ +## Summary + +The `Scope` data type represents the [Scope][] defined by a [ScopeDefinition][]. + +The `Scope` is defined by a number of levels: + +- [Tenant][Tenant Property] +- [System][System Property] +- [Package][Package Property] +- [Flow][Flow Property] + +Additional levels will be added in future releases, including: + +- Environment +- PackageVersion + +| | | +|---------------------|---------------------------------------------------------| +| **Category:** | Scopes | +| **Name:** | `Scope` | +| **Full Name:** | `Cortex.DataTypes.Scopes.Scope` | +| **Alias:** | N/A | +| **Description:** | Represents the [Scope][] defined by a [ScopeDefinition][]. | +| **Default Value:** | `null` | +| **Can be used as:** | `Scope`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Tenant + +The [Tenant][Tenant Property] the action is restricted to. + +| | | +|-----------------|-----------------------| +| Data Type | [String][] | + +### System + +The [System][System Property] the action is restricted to. + +| | | +|-----------------|-----------------------| +| Data Type | [String][] | + +### Package + +The [Package][Package Property] the action is restricted to. + +| | | +|-----------------|-----------------------| +| Data Type | [String][] | + +### Flow + +The [Flow][Flow Property] the action is restricted to. + +| | | +|-----------------|-----------------------| +| Data Type | [String][] | + +## Remarks + +### Create a Scope + +The following table shows some of the ways that `Scope` can be created. + +| Method | Example | Result | Editor Support | Notes | +|---------------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------| +| Use a `Scope` constructor | `new Scope("tenant", "system", "package", "flow")` | `{ "Tenant": "tenant", "System": "system", "Package": "package", "Flow": "flow" }` | N/A | Creates a new `Scope` that contains the scope values an action is restricted to. | + +### Convert Scope to Text + +The following table shows some of the ways that a `Scope` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|------------------------------------|---------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|---------------------|--------------------------------| +| Use `Convert Object To Json` block | where `Object` property has a value of `{ "Tenant": "tenant", "System": "system", "Package": "package", "Flow": "flow" }` | `"{\r\n \"Tenant\": \"tenant\",\r\n \"System\": \"system\",\r\n \"Package\": \"package\",\r\n \"Flow\": \"flow\"\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Scope`. +- The Literal Editor is available for [Input][] properties where the data type is `Scope`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Scope`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [ScopeDefinition][] + +### Related Concepts + +- [Working with Scopes][] + +### External Documentation + +None + +[Tenant Property]: {{< ref "#tenant">}} +[System Property]: {{< ref "#system">}} +[Package Property]: {{< ref "#package">}} +[Flow Property]: {{< ref "#flow">}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Scopes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Scopes.MainDoc">}} +[Scope]: {{< url path ="Cortex.Reference.DataTypes.Scopes.Scope.MainDoc">}} +[ScopeDefinition]: {{< url path ="Cortex.Reference.DataTypes.Scopes.ScopeDefinition.MainDoc">}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/session-details/_index.md b/content/en/docs/2024.9/Reference/data-types/session-details/_index.md new file mode 100644 index 000000000..43ba2d1b1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/session-details/_index.md @@ -0,0 +1,6 @@ +--- +title: "Session Details" +linkTitle: "Session Details" +description: "Data types used for working with sessions." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/session-details/serverdetails.md b/content/en/docs/2024.9/Reference/data-types/session-details/serverdetails.md new file mode 100644 index 000000000..e9f371b29 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/session-details/serverdetails.md @@ -0,0 +1,156 @@ +--- +title: "ServerDetails" +linkTitle: "ServerDetails" +description: "Used to represent details required to connect to a server." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.SessionDetails.ServerDetails)

+ +## Summary + +The `ServerDetails` data type is used to represent details required to connect to a server. + +| | | +|-|-| +| **Category:** | Session Details | +| **Name:** | `ServerDetails` | +| **Full Name:** | `Cortex.DataTypes.SessionDetails.ServerDetails` | +| **Alias:** | N/A | +| **Description:** | Details required to connect to a server. | +| **Default Value:** | null | +| **Can be used as:** | `ServerDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Host + +The Host is used to define the address of the server to connect to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +A server address can typically be represented in one of the following formats: + +- 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"`) + +The server address formats supported are dependent on the block being used: + +- [Send Email Using SMTP Server Block][Send Email Using SMTP Server Block Supported Server Address Formats] +- [Send Email Using Gmail Block][Send Email Using Gmail Block Supported Server Address Formats] + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### Port + +The Port is used to define the port on the server to connect to. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Int32][] with value `0` | + +### UseSsl + +UseSsl is used to define whether or not connection to the server should use [SSL][]. + +The value of this property depends on the [Port][Port Property] for the following blocks: + +- [Send Email Using SMTP Server Block][Send Email Using SMTP Server Block Setting UseSsl] +- [Send Email Using Gmail Block][Send Email Using Gmail Block Setting UseSsl] + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Boolean][] with value `true` | + +## Remarks + +### Create a ServerDetails + +The following table shows some of the ways that `ServerDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `ServerDetails` constructor | `new ServerDetails(host: "smtp.gmail.com", port: 465, useSsl: true)` | `{"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}` | Expression | | + +A `ServerDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Host` | `EncryptableText` | `"smtp.gmail.com"` | [Host][Host Property] defines the address of the server to connect to. | +| `Port` | `Int32` | `465` | [Port][Port Property] defines the port on the server to connect to. | +| `UseSsl` | `Boolean` | `true` | [UseSsl][UseSsl Property] defines whether or not connection to the server should use [SSL][]. | + +### Convert ServerDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}` | `"{\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ServerDetails`. +- The Literal Editor is available for [Input][] properties where the data type is `ServerDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ServerDetails`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [BasicEmailSessionDetails][] +- [Boolean][] +- [EncryptableText][] +- [Int32][] + +### Related Concepts + +- [Working with Email][] + +### External Documentation + +None + +[Host Property]: {{< ref "#host" >}} +[Port Property]: {{< ref "#port" >}} +[UseSsl Property]: {{< ref "#usessl" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[BasicEmailSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Email.BasicEmailSessionDetails.MainDoc" >}} + +[Send Email Using SMTP Server Block Supported Server Address Formats]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.SupportedServerAddressFormats" >}} +[Send Email Using SMTP Server Block Setting UseSsl]: {{< url path="Cortex.Reference.Blocks.Email.SendEmail.SendEmailUsingSmtpServer.SettingUseSsl" >}} + +[Send Email Using Gmail Block Supported Server Address Formats]: {{< url path="Cortex.Reference.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmail.SupportedServerAddressFormats" >}} +[Send Email Using Gmail Block Setting UseSsl]: {{< url path="Cortex.Reference.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmail.SettingUseSsl" >}} + +[Working with Email]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Email.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[SSL]: {{< url path="Cortex.Reference.Glossary.P-T.SSL" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/_index.md b/content/en/docs/2024.9/Reference/data-types/ssh/_index.md new file mode 100644 index 000000000..a5686346b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/_index.md @@ -0,0 +1,6 @@ +--- +title: "Ssh" +linkTitle: "Ssh" +description: "Data types used for working with SSH." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/authentication/ISshCredentials.md b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/ISshCredentials.md new file mode 100644 index 000000000..f4580d66d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/ISshCredentials.md @@ -0,0 +1,68 @@ +--- +title: "ISshCredentials" +linkTitle: "ISshCredentials" +description: "Any data type used to represent details required for authentication when working with SSH." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.Authentication.ISshCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required for authentication when working with SSH. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `ISshCredentials` | +| **Full Name:** | `Cortex.DataTypes.Ssh.Authentication.ISshCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required for authentication when working with SSH. | +| **Default Value:** | null | +| **Can be used as:** | `ISshCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `ISshCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `ISshCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `ISshCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [SshCertificateCredentials][] +- [SshCredentials][] +- [SshSessionDetails][] +- [SshUserCredentials][] +- [UserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} + +[SshSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.MainDoc" >}} +[SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} +[SshCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCertificateCredentials.MainDoc" >}} +[UserCredentials]: {{< url path="Cortex.Reference.DataTypes.Credentials.UserCredentials.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshCredentials.md b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshCredentials.md new file mode 100644 index 000000000..511df49b9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshCredentials.md @@ -0,0 +1,67 @@ +--- +title: "SshCredentials" +linkTitle: "SshCredentials" +description: "Any data type used to represent details required for authentication when working with SSH." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.Authentication.SshCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +Any data type used to represent details required for authentication when working with SSH. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `SshCredentials` | +| **Full Name:** | `Cortex.DataTypes.Ssh.Authentication.SshCredentials` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent details required for authentication when working with SSH. | +| **Default Value:** | null | +| **Can be used as:** | `SshCredentials`, `ISshCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SshCredentials`. +- The Literal Editor is not available for [Input][] properties where the data type is `SshCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SshCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [ISshCredentials][] +- [SshCertificateCredentials][] +- [SshUserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} + +[SshCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCertificateCredentials.MainDoc" >}} +[SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshUserCredentials.md b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshUserCredentials.md new file mode 100644 index 000000000..487316c87 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/SshUserCredentials.md @@ -0,0 +1,69 @@ +--- +title: "SshUserCredentials" +linkTitle: "SshUserCredentials" +description: "Used to represent password authentication credentials required to authenticate with an SSH server." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.Authentication.SshUserCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `SshUserCredentials` data type is used to represent password authentication credentials required to authenticate with an SSH server. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `SshUserCredentials` | +| **Full Name:** | `Cortex.DataTypes.Ssh.Authentication.SshUserCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent password authentication credentials required to authenticate with an SSH server. | +| **Default Value:** | null | +| **Can be used as:** | `SshUserCredentials`, `SshCredentials`, `ISshCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SshUserCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `SshUserCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SshUserCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [EncryptedText][] +- [ISshCredentials][] +- [SshCertificateCredentials][] +- [SshCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} + +[SshCertificateCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCertificateCredentials.MainDoc" >}} +[SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/authentication/_index.md b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/_index.md new file mode 100644 index 000000000..7fc50e16e --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/_index.md @@ -0,0 +1,6 @@ +--- +title: "Authentication" +linkTitle: "Authentication" +description: "Data types used for authenticating with servers." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/authentication/sshcertificatecredentials.md b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/sshcertificatecredentials.md new file mode 100644 index 000000000..b231ec5eb --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/authentication/sshcertificatecredentials.md @@ -0,0 +1,68 @@ +--- +title: "SshCertificateCredentials" +linkTitle: "SshCertificateCredentials" +description: "Used to represent public key credentials required to authenticate with an SSH server." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.Authentication.SshCertificateCredentials)

+ +{{% alert type="information" title="Information" %}} Improvements to this page are planned for the future. {{% /alert %}} + +## Summary + +The `SshCertificateCredentials` data type is used to represent public key credentials required to authenticate with an SSH server. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `SshCertificateCredentials` | +| **Full Name:** | `Cortex.DataTypes.Ssh.Authentication.SshCertificateCredentials` | +| **Alias:** | N/A | +| **Description:** | Used to represent public key credentials required to authenticate with an SSH server. | +| **Default Value:** | null | +| **Can be used as:** | `SshCertificateCredentials`, `SshCredentials`, `ISshCredentials`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SshCertificateCredentials`. +- The Literal Editor is available for [Input][] properties where the data type is `SshCertificateCredentials`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SshCertificateCredentials`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [EncryptedText][] +- [ISshCredentials][] +- [SshCredentials][] +- [SshUserCredentials][] + +### Related Concepts + +None + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} +[SshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshCredentials.MainDoc" >}} +[SshUserCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.SshUserCredentials.MainDoc" >}} + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/sshlogs.md b/content/en/docs/2024.9/Reference/data-types/ssh/sshlogs.md new file mode 100644 index 000000000..7490c8519 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/sshlogs.md @@ -0,0 +1,123 @@ +--- +title: "SshLogs" +linkTitle: "SshLogs" +description: "Used to represent logs returned by an SSH command." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.SshLogs)

+ +The `SshLogs` data type is used to represent the [WelcomeMessage][Welcome Message Property] returned from the [Host][]; the [TerminalPromptMatch][Terminal Prompt Match] found in the returned response; and the [Logs][Logs] from the SSH execution. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `SshLogs` | +| **Full Name:** | `Cortex.DataTypes.Ssh.SshLogs` | +| **Alias:** | N/A | +| **Description:** | `The SshLogs returned, containing the WelcomeMessage, TerminalPromptMatch and Logs.` | +| **Default Value:** | null | +| **Can be used as:** | `SshLogs`,`Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### WelcomeMessage + +Represents the message returned when first connecting to the [Host][]. It will return everything up until the first terminal prompt match. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### TerminalPromptMatch + +Represents the exact terminal prompt found in the response returned from the [Host][] that was matched by the [TerminalPrompt][] regex. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""`| + +### Logs + +Represents the details of the operations occurring during Ssh's execution. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with no value | + +## Exceptions + +None + +## Remarks + +### Create an SshLogs + +The following table shows some of the ways that an `SshLogs` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use an `SshLogs` constructor | `new SshLogs(welcomeMessage: "Welcome to Microsoft Ssh Server.", terminalPromptMatch: "C:/Users/CortexSshUser>", logs: "[Info] Connecting to Localhost. \n[Info] Welcome message received.")` | `{"WelcomeMessage": "Welcome to Microsoft Ssh Server.", "TerminalPromptMatch": "C:/Users/CortexSshUser>", "Logs": "[Info] Connecting to Localhost. \n[Info] Welcome message received."}` | Expression | | + +### Convert SshLogs to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"WelcomeMessage": "Welcome to Microsoft Ssh Server.", "TerminalPromptMatch": "C:/Users/CortexSshUser>", "Logs": "[Info] Connecting to Localhost. \n[Info] Welcome message received."}` | `"{\r\n \"WelcomeMessage\": \"Welcome to Microsoft Ssh Server.\",\r\n \"TerminalPromptMatch\": \"C:/Users/CortexSshUser>\",\r\n \"Logs\": \"[Info] Connecting to Localhost. \n[Info] Welcome message received.\"\r\n }"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SshLogs`. +- The Literal Editor is available for [Input][] properties where the data type is `SshLogs`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SshLogs`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [String][] +- [SshSessionDetails][] + +### Related Concepts + +None + +### External Documentation + +None + +[Welcome Message Property]: {{< ref "#welcomemessage" >}} +[Terminal Prompt Match]: {{< ref "#terminalpromptmatch" >}} +[Logs]: {{< ref "#logs" >}} + +[Host]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.Host" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.TerminalPrompt" >}} +[SshSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Ssh.SshSessionDetails.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/ssh/sshsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/ssh/sshsessiondetails.md new file mode 100644 index 000000000..219bb6ef9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/ssh/sshsessiondetails.md @@ -0,0 +1,163 @@ +--- +title: "SshSessionDetails" +linkTitle: "SshSessionDetails" +description: "Used to represent configuration for executing SSH commands on a specified host." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Ssh.SshSessionDetails)

+ +## Summary + +The `SshSessionDetails` data type is used to represent configuration for executing SSH commands on a specified host. + +| | | +|-|-| +| **Category:** | Ssh | +| **Name:** | `SshSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.Ssh.SshSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Configuration for executing SSH commands on a specified host. | +| **Default Value:** | `null` | +| **Can be used as:** | `SshSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Host + +The Host is used to define the address of the server to connect to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +A server address can typically be represented in one of the following formats: + +- Fully Qualified Domain Name (e.g. `"machine.domain.com"`) +- Machine name (e.g. `"server1"`) +- IP address (e.g. `"127.0.0.1"`) +- Localhost (e.g. `"localhost"`) + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### Port + +The Port is used to define the port on the server to connect to. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Int32][] with value `22` | + +### Credentials + +The Credentials are used to configure the [Domain][], [Username][] and [Password][] used to connect to the host. + +| | | +|--------------------|---------------------------| +| Data Type | [ISshCredentials][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [UserCredentials][] with value shown below: | + +```json +{ + "Domain": "", + "Username": "", + "Password": "" +} +``` + +### TerminalPrompt + +The regex used to match the host's terminal prompt. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `.*[>\|\$\|#]` | + +## Remarks + +### Create a SshSessionDetails + +The following table shows some of the ways that `SshSessionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `SshSessionDetails` constructor | `new SshSessionDetails(host: "localhost", port: 22, credentials: new UserCredentials(domain: "domain", username: "user", password: "password"), terminalPrompt: $@".*[>\|\$\|#]")` | `{"Host": "localhost", "Port": 22, "Credentials": { "Domain": "domain", "Username": "user", "Password": "## REDACTED ## - This value has been redacted as it contains text that should be encrypted, but is not."}, "TerminalPrompt": ".*[>\|\\$\|#]" }` | Expression | + +A `SshSessionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Host` | `EncryptableText` | `"localhost"` | [Host][] defines the address of the server to connect to. | +| `Port` | `Int32` | `22` | [Port][] defines the port on the server to connect to. | +| `Credentials` | `ISshCredentials` | `new UserCredentials(domain: "domain", username: "user", password: "password")` | [Credentials][] defines the credentials used to authenticate the connection to the server. | +| `TerminalPrompt` | `Int32` | `.*[>\|\$\|#]` | [TerminalPrompt][] defines the regex used to match the host's terminal prompt. | + +### Convert SshSessionDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Host": "localhost", "Port": 22, "Credentials": { "Domain": "domain", "Username": "user", "Password": "password"}, "TerminalPrompt": $@".*[>\|\\$\|#]"}` | `"{\r\n \"Host\": \"localhost\",\r\n \"Port\": 22,\r\n \"Credentials\": {\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"## REDACTED ## - This value has been redacted as it contains text that should be encrypted, but is not.\",\r\n},\r\n \"TerminalPrompt\": \".*[>\|\\\\$\|#]\"\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `SshSessionDetails`. +- The Literal Editor is available for [Input][] properties where the data type is `SshSessionDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SshSessionDetails`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [String][] +- [Int32][] +- [ISshCredentials] +- [UserCredentials] + +### Related Concepts + +None + +### External Documentation + +None + +[Host]: {{< ref "#host" >}} +[Port]: {{< ref "#port" >}} +[Credentials]: {{< ref "#credentials" >}} +[TerminalPrompt]: {{< ref "#terminalprompt" >}} + +[ISshCredentials]: {{< url path="Cortex.Reference.DataTypes.Ssh.Authentication.ISshCredentials.MainDoc" >}} + +[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" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/tasks/_index.md b/content/en/docs/2024.9/Reference/data-types/tasks/_index.md new file mode 100644 index 000000000..362aa29dd --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/tasks/_index.md @@ -0,0 +1,6 @@ +--- +title: "Tasks" +linkTitle: "Tasks" +description: "Data types used for working with Tasks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/tasks/executiontask.md b/content/en/docs/2024.9/Reference/data-types/tasks/executiontask.md new file mode 100644 index 000000000..e65cc5339 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/tasks/executiontask.md @@ -0,0 +1,163 @@ +--- +title: "ExecutionTask" +linkTitle: "ExecutionTask" +description: "Used to represent the asynchronous execution of a flow." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Tasks.ExecutionTask)

+ +## Summary + +Used to represent the asynchronous execution of a flow started by the [Run Flow Async][] block. + +| | | +|-|-| +| **Category:** | Tasks | +| **Name:** | `ExecutionTask` | +| **Full Name:** | `Cortex.DataTypes.Tasks.ExecutionTask` | +| **Alias:** | N/A | +| **Description:** | Used to represent the asynchronous execution of a flow started by the [Run Flow Async][] block. | +| **Default Value:** | `null` | +| **Can be used as:** | `ExecutionTask`, `IExecutionTask`, `ITask`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ExecutionId + +The unique Id of the execution of a flow. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | + +### Id + +The unique Id of the task. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | + +### IsCancelled + +This property returns `true` if the execution of the task has been cancelled, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompleted + +This property returns `true` if the execution of the task has completed, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompletedSuccessfully + +This property returns `true` if [IsCompleted][] is `true` and [IsFaulted][] is `false`, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsFaulted + +This property returns `true` if the execution of the task has thrown an exception, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### Status + +This property returns the state of the execution of the task (e.g. `"Cancelled"`, `"Faulted"`, `"RanToCompletion"`, `"Running"`) + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | + +### Exception + +This property returns the [Exception][] if thrown by the execution of the task, and `null` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Exception][] | + +## Remarks + +### Create an ExecutionTask + +The following table shows some of the ways that an `ExecutionTask` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Run Flow Async` Block | Where `Flow` property references a flow that will be run asynchronously | `{"ExecutionId": "00000000-0000-0000-0000-000000000000", "Id": "00000000-0000-0000-0000-000000000000", "IsCancelled": false, "IsCompleted": false, "IsCompletedSuccessfully": false, "IsFaulted": false, "Status": "Running", "Exception": null}` | N/A | See [Run Flow Async] | + +### Convert ExecutionTask to Text + +The following table shows some of the ways that an `ExecutionTask` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has an `ExecutionTask` value of `{"ExecutionId": "00000000-0000-0000-0000-000000000000", "Id": "00000000-0000-0000-0000-000000000000", "IsCancelled": false, "IsCompleted": false, "IsCompletedSuccessfully": false, "IsFaulted": false, "Status": "Running", "Exception": null}` | `"{\r\n \"ExecutionId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"Id\": \"00000000-0000-0000-0000-000000000000\",\r\n \"IsCancelled\": false,\r\n \"IsCompleted\": false,\r\n \"IsCompletedSuccessfully\": false,\r\n \"IsFaulted\": false,\r\n \"Status\": \"Running\",\r\n \"Exception\": null\r\n}"` | N/A | See [Convert Object To Json][] | + +### Retrieving the Results of an ExecutionTask + +Results (i.e. [Structure][] containing the [Output Variables][] of the flow) can be retrieved from any `ExecutionTask` whose status is `RanToCompletion` using the following blocks: +* [Wait For Task][] +* [Wait For All Tasks][] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `ExecutionTask`. +* The Literal Editor is not available for [Input][] properties where the data type is `ExecutionTask`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `ExecutionTask`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Boolean] +* [Exception][] +* [Guid][] +* [IExecutionTask][] +* [ITask<TResult>][ITask] +* [String][] +* [Structure][] + +### Related Concepts + +* [Working With Tasks][] + +### External Documentation + +None + +[Working With Tasks]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Tasks.MainDoc" >}} +[IsFaulted]: {{< ref "#isfaulted" >}} +[IsCompleted]: {{< ref "#iscompleted" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Output Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[Run Flow Async]: {{< url path="Cortex.Reference.Blocks.Flows.RunFlow.RunFlowAsync.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/tasks/iexecutiontask.md b/content/en/docs/2024.9/Reference/data-types/tasks/iexecutiontask.md new file mode 100644 index 000000000..ab0275885 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/tasks/iexecutiontask.md @@ -0,0 +1,165 @@ +--- +title: "IExecutionTask" +linkTitle: "IExecutionTask" +description: "Any data type representing an asynchronous execution of a flow." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Tasks.IExecutionTask)

+ +## Summary + +Any data type representing an asynchronous execution of a flow. + +| | | +|-|-| +| **Category:** | Tasks | +| **Name:** | `IExecutionTask` | +| **Full Name:** | `Cortex.DataTypes.Tasks.IExecutionTask` | +| **Alias:** | N/A | +| **Description:** | Any data type representing an asynchronous execution of a flow. | +| **Default Value:** | `null` | +| **Can be used as:** | `IExecutionTask`, `ITask`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### ExecutionId + +The unique Id of the execution of a flow. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | + +### Id + +The unique Id of the task. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | + +### IsCancelled + +This property returns `true` if the execution of the task has been cancelled, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompleted + +This property returns `true` if the execution of the task has completed, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompletedSuccessfully + +This property returns `true` if [IsCompleted][] is `true` and [IsFaulted][] is `false`, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsFaulted + +This property returns `true` if the execution of the task has thrown an exception, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### Status + +This property returns the state of the execution of the task (e.g. `"Cancelled"`, `"Faulted"`, `"RanToCompletion"`, `"Running"`) + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | + +### Exception + +This property returns the [Exception][] if thrown by the execution of the task, and `null` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Exception][] | + +## Remarks + +### Most Common IExecutionTask Data Types + +Any of the following data types can be used where an `IExecutionTask` is required: + +* [ExecutionTask][] + +### Create an IExecutionTask + +For some of the ways that an `IExecutionTask` can be created, please see each of the `IExecutionTask` data types: + +* [ExecutionTask][CreateExecutionTask] + +### Convert IExecutionTask to Text + +For some of the ways that an `IExecutionTask` can be converted to text see each of the `IExecutionTask` data types: + +* [ExecutionTask][ConvertExecutionTask] + +### Retrieving the Results of an IExecutionTask + +Results (i.e. [Structure][] containing the [Output Variables][] of the flow) can be retrieved from any `IExecutionTask` whose status is `RanToCompletion` using the following blocks: +* [Wait For Task][] +* [Wait For All Tasks][] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `IExecutionTask`. +* The Literal Editor is not available for [Input][] properties where the data type is `IExecutionTask`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `IExecutionTask`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Boolean] +* [Exception][] +* [ExecutionTask][] +* [Guid][] +* [ITask<TResult>][ITask] +* [String][] +* [Structure][] + +### Related Concepts + +* [Working With Tasks][] + +### External Documentation + +None + +[Working With Tasks]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Tasks.MainDoc" >}} +[IsFaulted]: {{< ref "#isfaulted" >}} +[CreateExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.Create" >}} +[IsCompleted]: {{< ref "#iscompleted" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} +[ExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.MainDoc" >}} +[Output Variables]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Variables.WhatIsAVariable.OutputVariablesStructure" >}} +[ConvertExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.Convert" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[Structure]: {{< url path="Cortex.Reference.DataTypes.Collections.Structure.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[ITask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ITask.MainDoc" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/tasks/itask-1.md b/content/en/docs/2024.9/Reference/data-types/tasks/itask-1.md new file mode 100644 index 000000000..2965e1a15 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/tasks/itask-1.md @@ -0,0 +1,150 @@ +--- +title: "ITask" +linkTitle: "ITask" +description: "Any data type representing an asynchronous task." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Tasks.ITask<TResult>)

+ +## Summary + +Any data type representing an asynchronous task. + +| | | +|-|-| +| **Category:** | Tasks | +| **Name:** | `ITask` | +| **Full Name:** | `Cortex.DataTypes.Tasks.ITask` | +| **Alias:** | N/A | +| **Description:** | Any data type representing an asynchronous task. | +| **Default Value:** | `null` | +| **Can be used as:** | `ITask`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Id + +The unique Id of the task. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | + +### IsCancelled + +This property returns `true` if the execution of the task has been cancelled, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompleted + +This property returns `true` if the execution of the task has completed, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsCompletedSuccessfully + +This property returns `true` if [IsCompleted][] is `true` and [IsFaulted][] is `false`, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### IsFaulted + +This property returns `true` if the execution of the task has thrown an exception, and `false` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Boolean][] | + +### Status + +This property returns the state of the execution of the task (e.g. `"Cancelled"`, `"Faulted"`, `"RanToCompletion"`, `"Running"`) + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | + +### Exception + +This property returns the [Exception][] if thrown by the execution of the task, and `null` otherwise. + +| | | +|--------------------|---------------------------| +| Data Type | [Exception][] | + +## Remarks + +### Most Common ITask<TResult> Data Types + +Any of the following data types can be used where an `ITask` is required: + +* [IExecutionTask][] +* [ExecutionTask][] + +### Create an ITask + +For some of the ways that an `ITask` can be created, please see each of the `ITask` data types: + +* [ExecutionTask][CreateExecutionTask] + +### Convert ITask<TResult> to Text + +For some of the ways that an `ITask` can be converted to text see each of the `ITask` data types: + +* [ExecutionTask][ConvertExecutionTask] + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `ITask`. +* The Literal Editor is not available for [Input][] properties where the data type is `ITask`. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `ITask`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Boolean] +* [Exception][] +* [Guid][] +* [ExecutionTask][] +* [IExecutionTask][] +* [String][] + +### Related Concepts + +* [Working With Tasks][] + +### External Documentation + +None + +[Working With Tasks]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Tasks.MainDoc" >}} +[CreateExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.Create" >}} +[IsFaulted]: {{< ref "#isfaulted" >}} +[IsCompleted]: {{< ref "#iscompleted" >}} +[Wait For Task]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForTask.MainDoc" >}} +[Wait For All Tasks]: {{< url path="Cortex.Reference.Blocks.Tasks.WaitForTask.WaitForAllTasksBlock.MainDoc" >}} +[Exception]: {{< url path="Cortex.Reference.DataTypes.Exceptions.Exception.MainDoc" >}} +[Boolean]: {{< url path="Cortex.Reference.DataTypes.ConditionalLogic.Boolean.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[IExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.MainDoc" >}} +[ConvertIExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.IExecutionTask.Convert" >}} +[ConvertExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.Convert" >}} +[ExecutionTask]: {{< url path="Cortex.Reference.DataTypes.Tasks.ExecutionTask.MainDoc" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/telnet/_index.md b/content/en/docs/2024.9/Reference/data-types/telnet/_index.md new file mode 100644 index 000000000..1184ed30a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/telnet/_index.md @@ -0,0 +1,6 @@ +--- +title: "Telnet" +linkTitle: "Telnet" +description: "Data types used for working with Telnet." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/telnet/telnetclienterrorcode.md b/content/en/docs/2024.9/Reference/data-types/telnet/telnetclienterrorcode.md new file mode 100644 index 000000000..4d7c97668 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/telnet/telnetclienterrorcode.md @@ -0,0 +1,194 @@ +--- +title: "TelnetClientErrorCode" +linkTitle: "TelnetClientErrorCode" +description: "Used to represent an error code explaining the reason a `TelnetClientException` occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Telnet.TelnetClientErrorCode)

+ +## Summary + +The `TelnetClientErrorCode` data type is used to represent an error code explaining the reason a [TelnetClientException][] occurred. For more information on the exception itself, see [TelnetClientException][]. + +`TelnetClientErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Telnet | +| **Name:** | `TelnetClientErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Telnet.TelnetClientErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [TelnetClientException][] occurred. | +| **Size:** | `4` bytes | +| **Default Value:** | `(TelnetClientErrorCode)0` | +| **Can be used as:** | `TelnetClientErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)TelnetClientErrorCode.InvalidHost` or `(System.Int16)TelnetClientErrorCode.InvalidHost` or `(short)TelnetClientErrorCode.InvalidHost`) | +| | `Int32` (e.g. `(Int32)TelnetClientErrorCode.InvalidHost` or `(System.Int32)TelnetClientErrorCode.InvalidHost` or `(int)TelnetClientErrorCode.InvalidHost`) | +| | `Int64` (e.g. `(Int64)TelnetClientErrorCode.InvalidHost` or `(System.Int64)TelnetClientErrorCode.InvalidHost` or `(long)TelnetClientErrorCode.InvalidHost`) | +| | `Single` (e.g. `(Single)TelnetClientErrorCode.InvalidHost` or `(System.Single)TelnetClientErrorCode.InvalidHost` or `(float)TelnetClientErrorCode.InvalidHost`) | +| | `Double` (e.g. `(Double)TelnetClientErrorCode.InvalidHost` or `(System.Double)TelnetClientErrorCode.InvalidHost` or `(double)TelnetClientErrorCode.InvalidHost`) | + +## Values + +### InvalidHost + +| | | +|-|-| +| **Name:** | InvalidHost | +| **Value:** | [Int32][] with value `100` | +| **Notes:** | Used when a [TelnetClientException][] occurred due to an invalid [Host][] provided in the [TelnetSessionDetails][]. See [Invalid Host][]| + +### InvalidPort + +| | | +|-|-| +| **Name:** | InvalidPort | +| **Value:** | [Int32][] with value `101` | +| **Notes:** | Used when a [TelnetClientException][] occurred due to an invalid [Port][] provided in the [TelnetSessionDetails][]. See [Invalid Port][]| + +### InvalidTerminalPrompt + +| | | +|-|-| +| **Name:** | InvalidTerminalPrompt | +| **Value:** | [Int32][] with value `102` | +| **Notes:** | Used when a [TelnetClientException][] occurred due to an invalid [TerminalPrompt][] provided in the [TelnetSessionDetails][]. See [Invalid Terminal Prompt][]| + +### InvalidSetting + +| | | +|-|-| +| **Name:** | InvalidSettings | +| **Value:** | [Int32][] with value `200` | +| **Notes:** | Used when a [TelnetClientException][] occurred due to an invalid setting provided in the [ConfigurationSettings][]. See [Invalid Settings][]| + +## Remarks + +### Create a TelnetClientErrorCode + +The following table shows some of the ways that a `TelnetClientErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TelnetClientErrorCode` expression | `TelnetClientErrorCode.InvalidHost` | `TelnetClientErrorCode.InvalidHost`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [Host][] provided in the [TelnetSessionDetails][] | +|| `TelnetClientErrorCode.InvalidPort` | `TelnetClientErrorCode.InvalidPort`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [Port][] provided in the [TelnetSessionDetails][] | +|| `TelnetClientErrorCode.InvalidTerminalPrompt` | `TelnetClientErrorCode.InvalidTerminalPrompt`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [TerminalPrompt][] provided in the [TelnetSessionDetails][] | +|| `TelnetClientErrorCode.InvalidSettings` | `TelnetClientErrorCode.InvalidSettings`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid setting provided in the [ConfigurationSettings][] | +| Use [Explicit Casting][] | `(TelnetClientErrorCode)100` | `TelnetClientErrorCode.InvalidHost`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [Host][] provided in the [TelnetSessionDetails][] | +|| `(TelnetClientErrorCode)101` | `TelnetClientErrorCode.InvalidPort`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [Port][] provided in the [TelnetSessionDetails][] | +|| `(TelnetClientErrorCode)102` | `TelnetClientErrorCode.InvalidTerminalPrompt`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid [TerminalPrompt][] provided in the [TelnetSessionDetails][]| +|| `(TelnetClientErrorCode)200` | `TelnetClientErrorCode.InvalidSettings`| Expression | Indicates a [TelnetClientException][] occurred due to an invalid setting provided in the [ConfigurationSettings][]| +| Use `Enum.Parse` | `(TelnetClientErrorCode)Enum.Parse(typeof(TelnetClientErrorCode), "InvalidHost")` | `TelnetClientErrorCode.InvalidHost`| Expression | Parses `"InvalidHost"` and converts it to `TelnetClientErrorCode.InvalidHost`. See [Enum.Parse][] | +|| `(TelnetClientErrorCode)Enum.Parse(typeof(TelnetClientErrorCode), "InvalidPort")` | `TelnetClientErrorCode.InvalidPort`| Expression | Parses `"InvalidPort"` and converts it to `TelnetClientErrorCode.InvalidPort`. See [Enum.Parse][] | +|| `(TelnetClientErrorCode)Enum.Parse(typeof(TelnetClientErrorCode), "InvalidTerminalPrompt")` | `TelnetClientErrorCode.InvalidTerminalPrompt`| Expression | Parses `"InvalidTerminalPrompt"` and converts it to `TelnetClientErrorCode.InvalidTerminalPrompt`. See [Enum.Parse][] | +|| `(TelnetClientErrorCode)Enum.Parse(typeof(TelnetClientErrorCode), "InvalidSettings")` | `TelnetClientErrorCode.InvalidSettings`| Expression | Parses `"InvalidSettings"` and converts it to `TelnetClientErrorCode.InvalidSettings`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(TelnetClientErrorCode)Enum.ToObject(typeof(TelnetClientErrorCode), 100)` | `TelnetClientErrorCode.InvalidHost`| Expression | Converts `100` to `TelnetClientErrorCode.InvalidHost` value. See [Enum.ToObject][] | +|| `(TelnetClientErrorCode)Enum.ToObject(typeof(TelnetClientErrorCode), 101)` | `TelnetClientErrorCode.InvalidPort`| Expression | Converts `101` to `TelnetClientErrorCode.InvalidPort` value. See [Enum.ToObject][] | +|| `(TelnetClientErrorCode)Enum.ToObject(typeof(TelnetClientErrorCode), 102)` | `TelnetClientErrorCode.InvalidTerminalPrompt`| Expression | Converts `102` to `TelnetClientErrorCode.InvalidTerminalPrompt` value. See [Enum.ToObject][] | +|| `(TelnetClientErrorCode)Enum.ToObject(typeof(TelnetClientErrorCode), 200)` | `TelnetClientErrorCode.InvalidSettings`| Expression | Converts `200` to `TelnetClientErrorCode.InvalidSettings` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert a TelnetClientErrorCode to Text + +The following table shows some of the ways that a `TelnetClientErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `TelnetClientErrorCode.InvalidHost.ToString()` | `"InvalidHost"` | Expression | Converts `TelnetClientErrorCode.InvalidHost` to `"InvalidHost"`. See [Enum.ToString][] | +|| `TelnetClientErrorCode.InvalidPort.ToString()` | `"InvalidPort"` | Expression | Converts `TelnetClientErrorCode.InvalidPort` to `"InvalidPort"`. See [Enum.ToString][] | +|| `TelnetClientErrorCode.InvalidTerminalPrompt.ToString()` | `"InvalidTerminalPrompt"` | Expression | Converts `TelnetClientErrorCode.InvalidTerminalPrompt` to `"InvalidTerminalPrompt"`. See [Enum.ToString][] | +|| `TelnetClientErrorCode.InvalidSettings.ToString()` | `"InvalidSettings"` | Expression | Converts `TelnetClientErrorCode.InvalidSettings` to `"InvalidSettings"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(TelnetClientErrorCode.InvalidHost)` | `"InvalidHost"` | Expression | Converts `TelnetClientErrorCode.InvalidHost` to `"InvalidHost"`. See [Convert.ToString][] | +|| `Convert.ToString(TelnetClientErrorCode.InvalidPort)` | `"InvalidPort"` | Expression | Converts `TelnetClientErrorCode.InvalidPort` to `"InvalidPort"`. See [Convert.ToString][] | +|| `Convert.ToString(TelnetClientErrorCode.InvalidTerminalPrompt)` | `"InvalidTerminalPrompt"` | Expression | Converts `TelnetClientErrorCode.InvalidTerminalPrompt` to `"InvalidTerminalPrompt"`. See [Convert.ToString][] | +|| `Convert.ToString(TelnetClientErrorCode.InvalidSettings)` | `"InvalidSettings"` | Expression | Converts `TelnetClientErrorCode.InvalidSettings` to `"InvalidSettings"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `TelnetClientErrorCode.InvalidHost` | `"InvalidHost"` | N/A | Converts `TelnetClientErrorCode.InvalidHost` to `"InvalidHost"`. See [Convert Object To Text][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidPort` | `"InvalidPort"` | N/A | Converts `TelnetClientErrorCode.InvalidPort` to `"InvalidPort"`. See [Convert Object To Text][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidTerminalPrompt` | `"InvalidTerminalPrompt"` | N/A | Converts `TelnetClientErrorCode.InvalidTerminalPrompt` to `"InvalidTerminalPrompt"`. See [Convert Object To Text][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidSettings` | `"InvalidSettings"` | N/A | Converts `TelnetClientErrorCode.InvalidSettings` to `"InvalidSettings"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `TelnetClientErrorCode.InvalidHost` | `"100"` | N/A | Converts `TelnetClientErrorCode.InvalidHost` to `"100"`. See [Convert Object To Json][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidPort` | `"101"` | N/A | Converts `TelnetClientErrorCode.InvalidPort` to `"101"`. See [Convert Object To Json][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidTerminalPrompt` | `"102"` | N/A | Converts `TelnetClientErrorCode.InvalidTerminalPrompt` to `"102"`. See [Convert Object To Json][] | +|| where `Object` property has a value of `TelnetClientErrorCode.InvalidSettings` | `"200"` | N/A | Converts `TelnetClientErrorCode.InvalidSettings` to `"200"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert a TelnetClientErrorCode to a Number + +The following table shows some of the ways that a `TelnetClientErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)TelnetClientErrorCode.InvalidHost` | `100` | Expression | [Casts][Explicit Casting] `TelnetClientErrorCode.InvalidHost` to `100` | +|| `(Int32)TelnetClientErrorCode.InvalidPort` | `101` | Expression | [Casts][Explicit Casting] `TelnetClientErrorCode.InvalidPort` to `101` | +|| `(Int32)TelnetClientErrorCode.InvalidTerminalPrompt` | `102` | Expression | [Casts][Explicit Casting] `TelnetClientErrorCode.InvalidTerminalPrompt` to `102` | +|| `(Int32)TelnetClientErrorCode.InvalidSettings` | `200` | Expression | [Casts][Explicit Casting] `TelnetClientErrorCode.InvalidSettings` to `200` | +| Use `Convert.ToInt32` | `Convert.ToInt32(TelnetClientErrorCode.InvalidHost)` | `100` | Expression | Converts `TelnetClientErrorCode.InvalidHost` to `100`. See [Convert.ToInt32][] | +|| `Convert.ToInt32(TelnetClientErrorCode.InvalidPort)` | `101` | Expression | Converts `TelnetClientErrorCode.InvalidPort` to `101`. See [Convert.ToInt32][] | +|| `Convert.ToInt32(TelnetClientErrorCode.InvalidTerminalPrompt)` | `102` | Expression | Converts `TelnetClientErrorCode.InvalidTerminalPrompt` to `102`. See [Convert.ToInt32][] | +|| `Convert.ToInt32(TelnetClientErrorCode.InvalidSettings)` | `200` | Expression | Converts `TelnetClientErrorCode.InvalidSettings` to `200`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TelnetClientErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `TelnetClientErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TelnetClientErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [TelnetClientException][] +- [TelnetSessionDetails][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[CloseSession]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.CloseSession" >}} + +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} + +[TelnetSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.MainDoc" >}} +[Port]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Port" >}} +[TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.TerminalPrompt" >}} +[ConfigurationSettings]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.ConfigurationSettings" >}} + +[TelnetClientException]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.MainDoc" >}} +[Invalid Host]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.InvalidHost" >}} +[Invalid Port]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.InvalidPort" >}} +[Invalid Terminal Prompt]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.InvalidTerminalPrompt" >}} +[Invalid Settings]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetClientException.InvalidSettings" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/telnet/telnetlogs.md b/content/en/docs/2024.9/Reference/data-types/telnet/telnetlogs.md new file mode 100644 index 000000000..6b0089fbb --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/telnet/telnetlogs.md @@ -0,0 +1,122 @@ +--- +title: "TelnetLogs" +linkTitle: "TelnetLogs" +description: "Used to represent logs returned by a telnet command." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Telnet.TelnetLogs)

+ +The `TelnetLogs` data type is used to represent the [WelcomeMessage][Welcome Message Property] returned from the [Host][]; the [TerminalPromptMatch][Terminal Prompt Match] found in the returned response; and the [Logs][Logs] from the telnet execution. + +| | | +|-|-| +| **Category:** | Telnet | +| **Name:** | `TelnetLogs` | +| **Full Name:** | `Cortex.DataTypes.Telnet.TelnetLogs` | +| **Alias:** | N/A | +| **Description:** | `The TelnetLogs returned, containing the WelcomeMessage, TerminalPromptMatch and Logs.` | +| **Default Value:** | null | +| **Can be used as:** | `TelnetLogs`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### WelcomeMessage + +Represents the message returned when first connecting to the [Host][]. It will return everything up until the first terminal prompt match. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with no value | + +### TerminalPromptMatch + +Represents the exact terminal prompt found in the response returned from the [Host][] that was matched by the [TerminalPrompt][] regex. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with no value | + +### Logs + +Represents the details of the operations occurring during Telnet's execution. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [String][] with no value | + +## Exceptions + +None + +## Remarks + +### Create a TelnetLogs + +The following table shows some of the ways that `TelnetLogs` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TelnetLogs` constructor | `new TelnetLogs(welcomeMessage: "Welcome to Microsoft Telnet Server.", terminalPromptMatch: "C:/Users/CortexTelnetUser>", logs: "[Info] Connecting to Localhost. \n[Info] Welcome message received.")` | `{"WelcomeMessage": "Welcome to Microsoft Telnet Server.", "TerminalPromptMatch": "C:/Users/CortexTelnetUser>", "Logs": "[Info] Connecting to Localhost. \n[Info] Welcome message received."}` | Expression | | + +### Convert TelnetLogs to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"WelcomeMessage": "Welcome to Microsoft Telnet Server.", "TerminalPromptMatch": "C:/Users/CortexTelnetUser>", "Logs": "[Info] Connecting to Localhost. \n[Info] Welcome message received."}` | `"{\r\n \"WelcomeMessage\": \"Welcome to Microsoft Telnet Server.\",\r\n \"TerminalPromptMatch\": \"C:/Users/CortexTelnetUser>\",\r\n \"Logs\": \"[Info] Connecting to Localhost. \n[Info] Welcome message received.\"\r\n }"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TelnetLogs`. +- The Literal Editor is available for [Input][] properties where the data type is `TelnetLogs`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TelnetLogs`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [String][] +- [TelnetSessionDetails][] + +### Related Concepts + +None + +### External Documentation + +None + +[Welcome Message Property]: {{< ref "#welcomemessage" >}} +[Terminal Prompt Match]: {{< ref "#terminalpromptmatch" >}} +[Logs]: {{< ref "#logs" >}} + +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[TerminalPrompt]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.TerminalPrompt" >}} +[TelnetSessionDetails]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/telnet/telnetservererrorcode.md b/content/en/docs/2024.9/Reference/data-types/telnet/telnetservererrorcode.md new file mode 100644 index 000000000..bca5a9915 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/telnet/telnetservererrorcode.md @@ -0,0 +1,130 @@ +--- +title: "TelnetServerErrorCode" +linkTitle: "TelnetServerErrorCode" +description: "Used to represent an error code explaining the reason a `TelnetServerException` occurred." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Telnet.TelnetServerErrorCode)

+ +## Summary + +The `TelnetServerErrorCode` data type is used to represent an error code explaining the reason a [TelnetServerException][] occurred. For more information on the exception itself, see [TelnetServerException][]. + +`TelnetServerErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Telnet | +| **Name:** | `TelnetServerErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Telnet.TelnetServerErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [TelnetServerException][] occurred. | +| **Size:** | `4` bytes | +| **Default Value:** | `(TelnetServerErrorCode)0` | +| **Can be used as:** | `TelnetServerErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)TelnetServerErrorCode.HostDisconnected` or `(System.Int16)TelnetServerErrorCode.HostDisconnected` or `(short)TelnetServerErrorCode.HostDisconnected`) | +| | `Int32` (e.g. `(Int32)TelnetServerErrorCode.HostDisconnected` or `(System.Int32)TelnetServerErrorCode.HostDisconnected` or `(int)TelnetServerErrorCode.HostDisconnected`) | +| | `Int64` (e.g. `(Int64)TelnetServerErrorCode.HostDisconnected` or `(System.Int64)TelnetServerErrorCode.HostDisconnected` or `(long)TelnetServerErrorCode.HostDisconnected`) | +| | `Single` (e.g. `(Single)TelnetServerErrorCode.HostDisconnected` or `(System.Single)TelnetServerErrorCode.HostDisconnected` or `(float)TelnetServerErrorCode.HostDisconnected`) | +| | `Double` (e.g. `(Double)TelnetServerErrorCode.HostDisconnected` or `(System.Double)TelnetServerErrorCode.HostDisconnected` or `(double)TelnetServerErrorCode.HostDisconnected`) | + +## Values + +### HostDisconnected + +| | | +|-|-| +| **Name:** | HostDisconnected | +| **Value:** | [Int32][] with value `100` | +| **Notes:** | Used when a [TelnetServerException][] occurred due the [Host][] provided disconnecting from the session without using [CloseSession]. See [Host Disconnected][]| + +## Remarks + +### Create a TelnetServerErrorCode + +The following table shows some of the ways that a `TelnetServerErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TelnetServerErrorCode` expression | `TelnetServerErrorCode.HostDisconnected` | `TelnetServerErrorCode.HostDisconnected`| Expression | Indicates a [TelnetServerException][] occurred due the [Host][] provided disconnecting from the session without using [CloseSession] | +| Use [Explicit Casting][] | `(TelnetServerErrorCode)100` | `TelnetServerErrorCode.HostDisconnected`| Expression | Indicates a [TelnetServerException][] occurred due the [Host][] provided disconnecting from the session without using [CloseSession] | +| Use `Enum.Parse` | `(TelnetServerErrorCode)Enum.Parse(typeof(TelnetServerErrorCode), "HostDisconnected")` | `TelnetServerErrorCode.HostDisconnected`| Expression | Parses `"HostDisconnected"` and converts it to `TelnetServerErrorCode.HostDisconnected`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(TelnetServerErrorCode)Enum.ToObject(typeof(TelnetServerErrorCode), 100)` | `TelnetServerErrorCode.HostDisconnected`| Expression | Converts `100` to `TelnetServerErrorCode.HostDisconnected` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert a TelnetServerErrorCode to Text + +The following table shows some of the ways that a `TelnetServerErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `TelnetServerErrorCode.HostDisconnected.ToString()` | `"HostDisconnected"` | Expression | Converts `TelnetServerErrorCode.HostDisconnected` to `"HostDisconnected"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(TelnetServerErrorCode.HostDisconnected)` | `"HostDisconnected"` | Expression | Converts `TelnetServerErrorCode.HostDisconnected` to `"HostDisconnected"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `TelnetServerErrorCode.HostDisconnected` | `"HostDisconnected"` | N/A | Converts `TelnetServerErrorCode.HostDisconnected` to `"HostDisconnected"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `TelnetServerErrorCode.HostDisconnected` | `"100"` | N/A | Converts `TelnetServerErrorCode.HostDisconnected` to `"100"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert a TelnetServerErrorCode to a Number + +The following table shows some of the ways that a `TelnetServerErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)TelnetServerErrorCode.HostDisconnected` | `100` | Expression | [Casts][Explicit Casting] `TelnetServerErrorCode.HostDisconnected` to `100` | +| Use `Convert.ToInt32` | `Convert.ToInt32(TelnetServerErrorCode.HostDisconnected)` | `100` | Expression | Converts `TelnetServerErrorCode.HostDisconnected` to `100`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TelnetServerErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `TelnetServerErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TelnetServerErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [TelnetServerException][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Host]: {{< url path="Cortex.Reference.DataTypes.Telnet.TelnetSessionDetails.Host" >}} +[CloseSession]: {{< url path="Cortex.Reference.Blocks.Telnet.ExecuteTelnetCommand.ExecuteTelnetCommand.CloseSession" >}} + +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[TelnetServerException]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetServerException.MainDoc" >}} +[Host Disconnected]: {{< url path="Cortex.Reference.Exceptions.Telnet.TelnetServerException.HostDisconnected" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/telnet/telnetsessiondetails.md b/content/en/docs/2024.9/Reference/data-types/telnet/telnetsessiondetails.md new file mode 100644 index 000000000..041047fb1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/telnet/telnetsessiondetails.md @@ -0,0 +1,133 @@ +--- +title: "TelnetSessionDetails" +linkTitle: "TelnetSessionDetails" +description: "Used to represent configuration for executing telnet commands on a specified host." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Telnet.TelnetSessionDetails)

+ +## Summary + +The `TelnetSessionDetails` data type is used to represent configuration for executing telnet commands on a specified host. + +| | | +|-|-| +| **Category:** | Telnet | +| **Name:** | `TelnetSessionDetails` | +| **Full Name:** | `Cortex.DataTypes.Telnet.TelnetSessionDetails` | +| **Alias:** | N/A | +| **Description:** | Configuration for executing telnet commands on a specified host. | +| **Default Value:** | `null` | +| **Can be used as:** | `TelnetSessionDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Host + +The Host is used to define the address of the server to connect to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see [EncryptableText][]. + +A server address can typically be represented in one of the following formats: + +- Fully Qualified Domain Name (e.g. `"machine.domain.com"`) +- Machine name (e.g. `"server1"`) +- IP address (e.g. `"127.0.0.1"`) +- Localhost (e.g. `"localhost"`) + +| | | +|--------------------|---------------------------| +| Data Type | [EncryptableText][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [EncryptableText][] with value `""` | + +### Port + +The Port is used to define the port on the server to connect to. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | [Int32][] with value `23` | + +### TerminalPrompt + +The regex used to match the host's terminal prompt. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | [String][] with value `(.*(~(.*[\r\n]?)\$\|>))` | + +## Remarks + +### Create a TelnetSessionDetails + +The following table shows some of the ways that `TelnetSessionDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TelnetSessionDetails` constructor | `new TelnetSessionDetails(host: "localhost", port: 23, terminalPrompt: $@"(.*(~(.*[\r\n]?)\$\|>))")` | `{"Host": "localhost", "Port": 23, "TerminalPrompt": "(.*(~(.*[\r\n]?)\$\|>))"}` | Expression | + +A `TelnetSessionDetails` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `Host` | `EncryptableText` | `"localhost"` | [Host][] defines the address of the server to connect to. | +| `Port` | `Int32` | `23` | [Port][] defines the port on the server to connect to. | +| `TerminalPrompt` | `String` | `(.*(~(.*[\r\n]?)\$\|>))` | [TerminalPrompt][] defines the regex used to match the host's terminal prompt. | + +### Convert TelnetSessionDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"Host": "localhost", "Port": 23, "TerminalPrompt": "(.*(~(.*[\\r\\n]?)\\$\|>))"}` | `"{\r\n \"Host\": \"localhost\",\r\n \"Port\": 23,\r\n \"TerminalPrompt\": \"(.*(~(.*[\\\\r\\\\n]?)\\\\$\|>))\"\r\n}"` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TelnetSessionDetails`. +- The Literal Editor is available for [Input][] properties where the data type is `TelnetSessionDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TelnetSessionDetails`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [String][] +- [Int32][] + +### Related Concepts + +None + +### External Documentation + +None + +[Host]: {{< ref "#host" >}} +[Port]: {{< ref "#port" >}} +[TerminalPrompt]: {{< ref "#terminalprompt" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/_index.md b/content/en/docs/2024.9/Reference/data-types/text/_index.md new file mode 100644 index 000000000..a3b6e67cc --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/_index.md @@ -0,0 +1,6 @@ +--- +title: "Text" +linkTitle: "Text" +description: "Data types used for working with text." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/text/char.md b/content/en/docs/2024.9/Reference/data-types/text/char.md new file mode 100644 index 000000000..ffa20506c --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/char.md @@ -0,0 +1,73 @@ +--- +title: "Char" +linkTitle: "Char" +description: "Used to represent unicode characters." +weight: 1 +--- + +# {{% param title %}} + +

(System.Char)

+ +## Summary + +The `Char` data type is used to represent unicode characters. + +The [String][] data type represents text as a sequence of `Char` values. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `Char` | +| **Full Name:** | `System.Char` | +| **Alias:** | `char` | +| **Description:** | A unicode character, surrounded by single quotes (e.g. `'a'` or `'!'`) | +| **Size:** | `2` bytes | +| **Default Value:** | `'\0'` or `'U0000'` | +| **Can be used as:** | `Int32`, `Int64`, `Single`, `Double`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)'a'` or `(System.Int16)'a'` or `(short)'a'`) | + +## Remarks + +### Create a Char + +The following table shows some of the ways that a `Char` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a character literal | `'a'` | `'a'` | Expression | | +| Declare a Unicode escape sequence | `'\u0061'` | `'a'` | Expression | | +| Declare a hexadecimal escape sequence | `'\x0061'` or `'\x061'` or `'\x61'`| `'a'` | Expression | | +| Cast an `Int32` value | `(Char)97` | `'a'` | Expression | | + +### Property Editor Support + +Currently no [Input][], [InputOutput][] or [Output][] properties require the `Char` data type. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +* [System.Char][] + +[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" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[System.Char]: {{< url path="MSDocs.DotNet.Api.System.Char.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/cultureinfo.md b/content/en/docs/2024.9/Reference/data-types/text/cultureinfo.md new file mode 100644 index 000000000..428c0e49f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/cultureinfo.md @@ -0,0 +1,116 @@ +--- +title: "CultureInfo" +linkTitle: "CultureInfo" +description: "Used to represent information about a specific culture, including the names for the culture, the writing system, the calendar used, the sort order of strings, and formatting for dates and numbers." +weight: 1 +--- + +# {{% param title %}} + +

(System.Globalization.CultureInfo)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `CultureInfo` data type is used to represent information about a specific culture, including the names for the culture, the writing system, the calendar used, the sort order of strings, and formatting for dates and numbers. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `CultureInfo` | +| **Full Name:** | `System.Globalization.CultureInfo` | +| **Alias:** | N/A | +| **Description:** | Used to represent information about a specific culture. | +| **Default Value:** | `null` | +| **Can be used as:** | `CultureInfo`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Types of CultureInfo + +There are four types of CultureInfo: + +- [Invariant Culture][] +- [Current Culture][] +- [Neutral Culture][] +- [Specific Culture][] + +#### Invariant Culture + +The invariant culture is culture-insensitive. It is associated with the English language but not with any country/region, as such the casing conventions, the sort order of strings, and formatting for dates and numbers will remain consistent across systems. This can be useful when persisting data in a culture-independent format. + +There are two ways to create an invariant culture: + +- `CultureInfo.InvariantCulture` +- `new CultureInfo("")` + +#### Current Culture + +The current culture is culture-sensitive. It is used to represent the current culture of the server running {{% ctx %}}, and as such the casing conventions, the sort order of strings, and formatting for dates and numbers may change across systems. This can be useful for providing date time in the correct format for a user. + +There is one way to get the current culture: + +- `CultureInfo.CurrentCulture` + +#### Neutral Culture + +The neutral culture is culture-sensitive. It is associated with a language, but not with any country/region. + +Neutral Culture can be created by specifying the language but not the country (e.g. `new CultureInfo("en")` for english with no associated country). + +#### Specific Culture + +The culture can be explicitly specified to use a particular format (e.g. `CultureInfo("en-GB")` for the standard UK english culture). +If the resources for a specific culture are not available in the operating system, the resources for the associated neutral culture are used. + +For a comprehensive list of cultures please see [Supported Culture Codes][]. + +### Invalid CultureInfo + +If an invalid CultureInfo (e.g. `new CultureInfo(“enaa”)`), is provided to a block property that requires an [IFormatProvider][] data type, (i.e. [Format Text With Values][FormatTextWithValues] block) a [CultureInfoNotFoundException][] will be thrown. + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `CultureInfo`. +- The Literal Editor is available for [Input][] properties where the data type is `CultureInfo`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `CultureInfo`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [IFormatProvider][] + +### Related Concepts + +- [Working with Text][] + +### External Documentation + +- [Supported Culture Codes][] +- [System.Globalization.CultureInfo][] +- [System.Globalization.CultureInfoNotFoundException][CultureInfoNotFoundException] + +[CultureInfoNotFoundException]: {{< url path = "MSDocs.DotNet.Api.System.Globalization.CultureInfoNotFoundException">}} +[Supported Culture Codes]: {{< url path = "MSDocs.CSharp.SupportedCultureCodes">}} + +[Invariant Culture]: {{< ref "#invariant-culture" >}} +[Current Culture]: {{< ref "#current-culture" >}} +[Specific Culture]: {{< ref "#specific-culture" >}} +[Neutral Culture]: {{< ref "#neutral-culture" >}} + +[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" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[System.Globalization.CultureInfo]: {{< url path="MSDocs.DotNet.Api.System.Globalization.CultureInfo" >}} +[FormatTextWithValues]: {{< url path="Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues.MainDoc" >}} +[IFormatProvider]: {{< url path="Cortex.Reference.DataTypes.Text.IFormatProvider.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/encoding.md b/content/en/docs/2024.9/Reference/data-types/text/encoding.md new file mode 100644 index 000000000..99f8b08e9 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/encoding.md @@ -0,0 +1,65 @@ +--- +title: "Encoding" +linkTitle: "Encoding" +description: "Any data type used to represent a specific character encoding (e.g. ASCII, UTF8, Unicode)." +weight: 1 +--- + +# {{% param title %}} + +

(System.Text.Encoding)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +Any data type used to represent a specific character encoding (e.g. ASCII, UTF8, Unicode). + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `Encoding` | +| **Full Name:** | `System.Text.Encoding` | +| **Alias:** | N/A | +| **Description:** | Any data type used to represent a specific character encoding (e.g. ASCII, UTF8, Unicode). | +| **Default Value:** | `null` | +| **Can be used as:** | `Encoding`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Encoding`. +- The Literal Editor is available for [Input][] properties where the data type is `Encoding`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Encoding`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [UnicodeEncoding][] +- [UTF32Encoding][] +- [UTF8Encoding][] + +### Related Concepts + +- [Working with Text][] + +### External Documentation + +- [System.Text.Encoding][Encoding] + +[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" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} +[Encoding]: {{< url path = "MSDocs.DotNet.Api.System.Text.Encoding">}} +[UnicodeEncoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UnicodeEncoding.MainDoc">}} +[UTF32Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF32Encoding.MainDoc">}} +[UTF8Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF8Encoding.MainDoc">}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/encryptabletext.md b/content/en/docs/2024.9/Reference/data-types/text/encryptabletext.md new file mode 100644 index 000000000..571986655 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/encryptabletext.md @@ -0,0 +1,63 @@ +--- +title: "EncryptableText" +linkTitle: "EncryptableText" +description: "Used to represent text that can be, but does not need to be encrypted." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.EncryptableText)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `EncryptableText` datatype is used to represent text that can be, but does not need to be encrypted. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `EncryptableText` | +| **Full Name:** | `Cortex.DataTypes.Text.EncryptableText` | +| **Alias:** | N/A | +| **Description:** | Used to represent text that can be, but does not need to be encrypted . | +| **Default Value:** | `null` | +| **Can be used as:** | `EncryptableText`, `object`, `dynamic` | +| **Can be cast to:** | `string` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EncryptableText`. +- The Literal Editor is available for [Input][] properties where the data type is `EncryptableText`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EncryptableText`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptedText] +- [String] + +### Related Concepts + +- [Working with Text] + +### External Documentation + +None + +[EncryptedText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptedText.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/encryptedtext.md b/content/en/docs/2024.9/Reference/data-types/text/encryptedtext.md new file mode 100644 index 000000000..ae64300ec --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/encryptedtext.md @@ -0,0 +1,63 @@ +--- +title: "EncryptedText" +linkTitle: "EncryptedText" +description: "Used to represent text that must be encrypted." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.EncryptedText)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `EncryptedText` datatype is used to represent text that must be encrypted. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `EncryptedText` | +| **Full Name:** | `Cortex.DataTypes.Text.EncryptedText` | +| **Alias:** | N/A | +| **Description:** | Used to represent text that must be encrypted . | +| **Default Value:** | `null` | +| **Can be used as:** | `EncryptedText`, `object`, `dynamic` | +| **Can be cast to:** | `string` | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `EncryptedText`. +- The Literal Editor is available for [Input][] properties where the data type is `EncryptedText`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `EncryptedText`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [EncryptableText][] +- [String][] + +### Related Concepts + +- [Working with Text] + +### External Documentation + +None + +[EncryptableText]: {{< url path="Cortex.Reference.DataTypes.Text.EncryptableText.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/iformatprovider.md b/content/en/docs/2024.9/Reference/data-types/text/iformatprovider.md new file mode 100644 index 000000000..60489d7d1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/iformatprovider.md @@ -0,0 +1,63 @@ +--- +title: "IFormatProvider" +linkTitle: "IFormatProvider" +description: "Any data type used to control formatting." +weight: 1 +--- + +# {{% param title %}} + +

(System.IFormatProvider)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +Any data type used to control formatting. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `IFormatProvider` | +| **Full Name:** | `System.IFormatProvider` | +| **Alias:** | N/A | +| **Description:** | Any data type used to control formatting. | +| **Default Value:** | `null` | +| **Can be used as:** | `IFormatProvider`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `IFormatProvider`. +- The Literal Editor is available for [Input][] properties where the data type is `IFormatProvider`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `IFormatProvider`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [CultureInfo][] + +### Related Concepts + +- [Working with Text][] + +### External Documentation + +- [System.IFormatProvider][IFormatProvider] + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[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" >}} + +[IFormatProvider]: {{< url path="MSDocs.DotNet.Api.System.IFormatProvider" >}} + +[CultureInfo]: {{< url path="Cortex.Reference.DataTypes.Text.CultureInfo.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/regex/_index.md b/content/en/docs/2024.9/Reference/data-types/text/regex/_index.md new file mode 100644 index 000000000..fd0bae889 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/regex/_index.md @@ -0,0 +1,6 @@ +--- +title: "Regex" +linkTitle: "Regex" +description: "Data types used when working with Regex." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/text/regex/capturedetails.md b/content/en/docs/2024.9/Reference/data-types/text/regex/capturedetails.md new file mode 100644 index 000000000..f1aae5ce8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/regex/capturedetails.md @@ -0,0 +1,129 @@ +--- +title: "CaptureDetails" +linkTitle: "CaptureDetails" +description: "Used to represent a single capture for a given group" +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.CaptureDetails)

+ +## Summary + +The `CaptureDetails` data type is used to represent a single capture for a given [Group][]. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `CaptureDetails` | +| **Full Name:** | `Cortex.DataTypes.Text.Regex.CaptureDetails` | +| **Alias:** | N/A | +| **Description:** | A `CaptureDetails` represents a single capture for a given [Group][]. | +| **Default Value:** | null | +| **Can be used as:** | `CaptureDetails`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Value + +The value of the capture. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with no value | + +### Index + +The starting index of the capture. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +### Length + +The length of the [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +## Remarks + +### Create a CaptureDetails + +The following table shows some of the ways that a `CaptureDetails` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `CaptureDetails` constructor with object initialisation | `new CaptureDetails{Value = "", Index = 0, Length = 0}` | `{"Value": "","Index": 0,"Length": 0}` | Expression | | + +### Convert a CaptureDetails to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)CaptureDetails.ToString()` | `"Cortex.DataTypes.Text.Regex.CaptureDetails"` | Expression | ToString will return the Full Name of the `CaptureDetails` Data Type | +| Use `Convert Object to Text` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0}` | `"Cortex.DataTypes.Text.Regex.CaptureDetails"` | N/A | See [Convert Object to Text][] | +| Use `Convert Object to Json` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0}` | `"{\r\n \"Value\": \"\",\r\n \"Index\": 0,\r\n \"Length\": 0\r\n}"` | N/A | See [Convert Object to Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `CaptureDetails`. +- The Literal Editor is not available for [Input][] properties where the data type is `CaptureDetails`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `CaptureDetails`. + +### Known Limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `CaptureDetails`, then its Full Name will be returned; instead of a representation of the data within the `CaptureDetails`. + +In future this limitation may be removed. + +## See Also + +### Related Data Types + +* [Group][] +* [Int32][] +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +None + +[Value Property]: {{}} +[Index Property]: {{}} +[Length Property]: {{}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[System.Text.RegularExpressions.Capture]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.Capture" >}} + +[Group]: {{}} +[Int32]: {{}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/regex/group.md b/content/en/docs/2024.9/Reference/data-types/text/regex/group.md new file mode 100644 index 000000000..1b11e02e1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/regex/group.md @@ -0,0 +1,145 @@ +--- +title: "Group" +linkTitle: "Group" +description: "Used to represent a regex match group. It contains all of the captures for a given group pattern." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.Group)

+ +## Summary + +The `Group` data type is used to represent a regex [Match][] group. It contains all of the [Captures][CaptureDetails] for a given group pattern. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `Group` | +| **Full Name:** | `Cortex.DataTypes.Text.Regex.Group` | +| **Alias:** | N/A | +| **Description:** | A `Group` represents a regex [Match][] group. It contains all of the [Captures][CaptureDetails] for a given group pattern. | +| **Default Value:** | null | +| **Can be used as:** | `Group`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Value + +The value of the last [CaptureDetails][] within [Captures][Captures Property], this represents the full text captured by the Group. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with no value. | + +### Index + +The starting index of the first [CaptureDetails][] within [Captures][Captures Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +### Length + +The length of [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +### Captures + +The list of [CaptureDetails][CaptureDetails] found in the Group. +

If no captures were found, the list will be empty. + +| | | +|--------------------|---------------------------| +| Data Type | [IReadOnlyList]<[CaptureDetails][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [IReadOnlyList][]<[CaptureDetails][]> with no value | + +## Remarks + +### Create a Group + +The following table shows some of the ways that a `Group` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Group` constructor with object initialisation | `new Group{Value = "", Index = 0, Length = 0, Captures = new List()}` | `{"Value": "","Index": 0,"Length": 0,"Captures": []}` | Expression | | + +### Convert a Group to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)Group.ToString()` | `"Cortex.DataTypes.Text.Regex.Group"` | Expression | ToString will return the Full Name of the `Group` Data Type | +| Use `Convert Object to Text` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0,"Captures": new List()}` | `"Cortex.DataTypes.Text.Regex.Group"` | N/A | See [Convert Object to Text][] | +| Use `Convert Object to Json` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0,"Captures": []}` | `"{\r\n \"Value\": \"\",\r\n \"Index\": 0,\r\n \"Length\": 0,\r\n \"Captures\": []\r\n}"` | N/A | See [Convert Object to Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Group`. +- The Literal Editor is not available for [Input][] properties where the data type is `Group`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Group`. + +### Known Limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `Group`, then its Full Name will be returned; instead of a representation of the data within the `Group`. + +In future this limitation may be removed. + +## See Also + +### Related Data Types + +* [CaptureDetails][] +* [IReadOnlyList][] +* [Int32][] +* [Match][] +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +None + +[Captures Property]: {{}} +[Value Property]: {{}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[System.Text.RegularExpressions.Group]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.Group" >}} + +[CaptureDetails]: {{}} +[IReadOnlyList]: {{}} +[Dictionary]: {{}} +[Int32]: {{}} +[Match]: {{}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/regex/match.md b/content/en/docs/2024.9/Reference/data-types/text/regex/match.md new file mode 100644 index 000000000..6e32fef61 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/regex/match.md @@ -0,0 +1,140 @@ +--- +title: "Match" +linkTitle: "Match" +description: "Used to represent a regex match. It contains all of the groups found in the regex pattern." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.Match)

+ +## Summary + +The `Match` data type is used to represent a regex match. It contains all of the [Groups][Group] found in the regex pattern. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `Match` | +| **Full Name:** | `Cortex.DataTypes.Text.Regex.Match` | +| **Alias:** | N/A | +| **Description:** | A `Match` represents a regex match. It contains all of the [Groups][Group] found in the regex pattern. | +| **Default Value:** | null | +| **Can be used as:** | `Match`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Value + +The value of the text that was matched + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with no value | + +### Index + +The starting index of the regex match. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +### Length + +The length of [Value][Value Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Int32][] with value `0` | + +### Groups + +The dictionary of [Groups][Group] in the match.

Each key in [Groups][Groups Property] represents the name of the [Group][], if a group does not have a name provided they will increment from `"1"` + +[Groups][Groups Property] always contains a default [Group][] representing the full match, the name of this [Group][] is always `"0"`. + +| | | +|--------------------|---------------------------| +| Data Type | [Dictionary][]<[String][], [Group][]> | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [Dictionary][]<[String][], [Group][]> with value `{}` | + +## Remarks + +### Create a Match + +The following table shows some of the ways that a `Match` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `Match` constructor with object initialisation | `new Match{Value = "", Index = 0, Length = 0, Groups = new Dictionary()}` | `{"Value": "","Index": 0,"Length": 0,"Groups": {}}` | Expression | | + +### Convert Match to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `($)Match.ToString()` | `"Cortex.DataTypes.Text.Regex.Match"` | Expression | ToString will return the Full Name of the `Match` Data Type | +| Use `Convert Object to Text` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0,"Groups": {}}` | `"Cortex.DataTypes.Text.Regex.Match"` | N/A | See [Convert Object to Text][] | +| Use `Convert Object to Json` block | where `Object` property has a value of `{"Value": "","Index": 0,"Length": 0,"Groups": {}}` | `"{\r\n \"Value\": \"\",\r\n \"Index\": 0,\r\n \"Length\": 0,\r\n \"Groups\": {}\r\n}"` | N/A | See [Convert Object to Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `Match`. +- The Literal Editor is not available for [Input][] properties where the data type is `Match`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `Match`. + +### Known Limitations + +#### ToString Method always returns the Full Name + +Currently, if the `ToString()` method is used on a `Match`, then its Full Name will be returned; instead of a representation of the data within the `Match`. + +In future this limitation may be removed. + +## See Also + +### Related Data Types + +* [Dictionary][] +* [Group][] +* [Int32][] +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +None + +[Groups Property]: {{}} +[Value Property]: {{}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Dictionary]: {{}} +[Int32]: {{}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Group]: {{}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/searchoptions.md b/content/en/docs/2024.9/Reference/data-types/text/searchoptions.md new file mode 100644 index 000000000..dc12ef04d --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/searchoptions.md @@ -0,0 +1,166 @@ +--- +title: "SearchOptions" +linkTitle: "SearchOptions" +description: "Used to specify how text is matched when performing a search (i.e. text matches the specified literal text, regex or pattern)." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.SearchOptions)

+ +## Summary + +The `SearchOptions` are used to specify how text is matched when performing a search (i.e. text matches the specified literal text, regex or pattern). + +`SearchOptions` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `SearchOptions` | +| **Full Name:** | `Cortex.DataTypes.Text.SearchOptions` | +| **Alias:** | N/A | +| **Description:** | Specifies how text is matched when performing a search (i.e. text matches the specified literal text, regex or pattern). | +| **Default Value:** | `(SearchOptions)0` | +| **Can be used as:** | `SearchOptions`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)SearchOptions.LiteralText` or `(System.Int16)SearchOptions.LiteralText` or `(short)SearchOptions.LiteralText`) | +| | `Int32` (e.g. `(Int32)SearchOptions.LiteralText` or `(System.Int32)SearchOptions.LiteralText` or `(int)SearchOptions.LiteralText`) | +| | `Int64` (e.g. `(Int64)SearchOptions.LiteralText` or `(System.Int64)SearchOptions.LiteralText` or `(long)SearchOptions.LiteralText`) | +| | `Single` (e.g. `(Single)SearchOptions.LiteralText` or `(System.Single)SearchOptions.LiteralText` or `(float)SearchOptions.LiteralText`) | +| | `Double` (e.g. `(Double)SearchOptions.LiteralText` or `(System.Double)SearchOptions.LiteralText` or `(double)SearchOptions.LiteralText`) | + +## Values + +### LiteralText + +| | | +|-|-| +| **Name:** | LiteralText | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Matches text exactly with a literal character search. | + +### Regex + +| | | +|-|-| +| **Name:** | Regex | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Matches text that matches the [regex][Regex Syntax] provided. | + +### PatternMatching + +| | | +|-|-| +| **Name:** | PatternMatching | +| **Value:** | [Int32][] with value `2` | +| **Notes:** | Matches text that matches the [pattern][Pattern Matching Syntax] provided. | + +## Remarks + +### Create SearchOptions + +The following table shows some of the ways that `SearchOptions` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `SearchOptions` literal | `LiteralText` | `SearchOptions.LiteralText` | Literal | Matches text exactly with a literal character search. | +| | `Regex` | `SearchOptions.Regex` | Literal | Matches text that matches the regex provided, see [Regex Syntax][]. | +| | `PatternMatching` | `SearchOptions.PatternMatching` | Literal | Matches text that matches the pattern provided, see [Pattern Matching Syntax][]. | +| Use a `SearchOptions` expression | `SearchOptions.LiteralText` | `SearchOptions.LiteralText`| Expression | Matches text exactly with a literal character search.| +| | `SearchOptions.Regex` | `SearchOptions.Regex`| Expression | Matches text that matches the regex provided, see [Regex Syntax][]. | +| | `SearchOptions.PatternMatching` | `SearchOptions.PatternMatching`| Expression | Matches text that matches the pattern provided, see [Pattern Matching Syntax][]. | +| Use [Explicit Casting][] | `(SearchOptions)0` | `SearchOptions.LiteralText`| Expression | Matches text exactly with a literal character search. | +| | `(SearchOptions)1` | `SearchOptions.Regex`| Expression | Matches text that matches the regex provided, see [Regex Syntax][]. | +| | `(SearchOptions)2` | `SearchOptions.PatternMatching`| Expression | Matches text that matches the pattern provided, see [Pattern Matching Syntax][]. | +| Use `Enum.Parse` | `(SearchOptions)Enum.Parse(typeof(SearchOptions), "LiteralText")` | `SearchOptions.LiteralText`| Expression | Parses `"LiteralText"` and converts it to `SearchOptions.LiteralText`. See [Enum.Parse][] | +| | `(SearchOptions)Enum.Parse(typeof(SearchOptions), "Regex")` | `SearchOptions.Regex`| Expression | Parses `"Regex"` and converts it to `SearchOptions.Regex`. See [Enum.Parse][] | +| | `(SearchOptions)Enum.Parse(typeof(SearchOptions), "PatternMatching")` | `SearchOptions.PatternMatching`| Expression | Parses `"PatternMatching"` and converts it to `SearchOptions.PatternMatching`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(SearchOptions)Enum.ToObject(typeof(SearchOptions), 0)` | `SearchOptions.LiteralText`| Expression | Converts `0` to `SearchOptions.LiteralText` value. See [Enum.ToObject][] | +| | `(SearchOptions)Enum.ToObject(typeof(SearchOptions), 1)` | `SearchOptions.Regex`| Expression | Converts `1` to `SearchOptions.Regex` value. See [Enum.ToObject][] | +| | `(SearchOptions)Enum.ToObject(typeof(SearchOptions), 2)` | `SearchOptions.PatternMatching`| Expression | Converts `2` to `SearchOptions.PatternMatching` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert SearchOptions to Text + +The following table shows some of the ways that a `SearchOptions` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `SearchOptions.LiteralText.ToString()` | `"LiteralText"` | Expression | Converts `SearchOptions.LiteralText` to `"LiteralText"`. See [Enum.ToString][] | +| | `SearchOptions.Regex.ToString()` | `"Regex"` | Expression | Converts `SearchOptions.Regex` to `"Regex"`. See [Enum.ToString][] | +| | `SearchOptions.PatternMatching.ToString()` | `"PatternMatching"` | Expression | Converts `SearchOptions.PatternMatching` to `"PatternMatching"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(SearchOptions.LiteralText)` | `"LiteralText"` | Expression | Converts `SearchOptions.LiteralText` to `"LiteralText"`. See [Convert.ToString][] | +| | `Convert.ToString(SearchOptions.Regex)` | `"Regex"` | Expression | Converts `SearchOptions.Regex` to `"Regex"`. See [Convert.ToString][] | +| | `Convert.ToString(SearchOptions.PatternMatching)` | `"PatternMatching"` | Expression | Converts `SearchOptions.PatternMatching` to `"PatternMatching"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `SearchOptions.LiteralText` | `"LiteralText"` | N/A | Converts `SearchOptions.LiteralText` to `"LiteralText"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `SearchOptions.Regex` | `"Regex"` | N/A | Converts `SearchOptions.Regex` to `"Regex"`. See [Convert Object To Text][] || | where `Object` property has a value of `SearchOptions.Regex` | `"Regex"` | N/A | |Converts `SearchOptions.Regex` to `"Regex"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `SearchOptions.PatternMatching` | `"PatternMatching"` | N/A | Converts `SearchOptions.PatternMatching` to `"PatternMatching"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `SearchOptions.LiteralText` | `"0"` | N/A | Converts `SearchOptions.LiteralText` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `SearchOptions.Regex` | `"1"` | N/A | Converts `SearchOptions.Regex` to `"1"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `SearchOptions.PatternMatching` | `"2"` | N/A | Converts `SearchOptions.PatternMatching` to `"2"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert SearchOptions to a Number + +The following table shows some of the ways that a `SearchOptions` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)SearchOptions.LiteralText` | `0` | Expression | [Casts][Explicit Casting] `SearchOptions.LiteralText` to `0` | +| | `(Int32)SearchOptions.Regex` | `1` | Expression | [Casts][Explicit Casting] `SearchOptions.Regex` to `1` | +| | `(Int32)SearchOptions.PatternMatching` | `2` | Expression | [Casts][Explicit Casting] `SearchOptions.PatternMatching` to `2` | +| Use `Convert.ToInt32` | `Convert.ToInt32(SearchOptions.LiteralText)` | `0` | Expression | Converts `SearchOptions.LiteralText` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(SearchOptions.Regex)` | `1` | Expression | Converts `SearchOptions.Regex` to `1`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(SearchOptions.PatternMatching)` | `2` | Expression | Converts `SearchOptions.PatternMatching` to `2`. See [Convert.ToInt32][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `SearchOptions`. +* The Literal Editor is available for [Input][] properties where the data type is `SearchOptions`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `SearchOptions`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Int32][] +* [String][] + +### Related Concepts + +* [Working with Enums][] +* [Explicit Casting][] + +### External Documentation + +None + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Pattern Matching Syntax]: {{}} +[Regex Syntax]: {{}} +[String Equality]: {{}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/string.md b/content/en/docs/2024.9/Reference/data-types/text/string.md new file mode 100644 index 000000000..2ea47eaee --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/string.md @@ -0,0 +1,83 @@ +--- +title: "String" +linkTitle: "String" +description: "Used to represent text." +weight: 1 +--- + +# {{% param title %}} + +

(System.String)

+ +## Summary + +The `String` data type is used to represent text. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `String` | +| **Full Name:** | `System.String` | +| **Alias:** | `string` | +| **Description:** | A sequence of unicode [characters][Char], surrounded by double quotes (e.g. `"This is a string"`) | +| **Size:** | Varies depending upon the number of [characters][Char] it contains | +| **Default Value:** | `null` | +| **Can be used as:** | `IEnumerable`, `IEnumerable`, `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Create a String + +The following table shows some of the ways that a `String` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `String` literal | `"Hello World!"` | `"Hello World!"` | Literal, Expression | In the Expression Editor the surrounding double quotes (i.e. `""`) are needed (e.g. `"Hello World!"`); in the Literal Editor they are not (e.g. `Hello World!`). Any double quotes in the Literal Editor will be treated as literal characters that are part of the `String`. | +| Use a `String` expression | `$"Hello {($)Variable}!"` where `($)Variable` is set to `"World!"` | `"Hello World!"` | Expression | Uses [String Interpolation][] | +| | `String.Format("Hello {0}!", ($)Variable)` where `($)Variable` is set to `"World!"` | `"Hello World!"` | Expression | Uses [String.Format][] | +| | `String.Concat("Hello", " ", "World!")` | `"Hello World!"` | Expression | Uses [String.Concat][] | +| | `String.Join(" ", {"Hello", "World!"})` | `"Hello World!"` | Expression | Uses [String.Join][] | +| | `"Hello!".Insert(5, " World")` | `"Hello World!"` | Expression | Uses [String.Insert][] | +| | `"Hello" + " " + "World!"` | `"Hello World!"` | Expression | Uses [String Concatenation Operator][] (i.e. `+`) | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `String`. +* The Literal Editor is available for [Input][] properties where the data type is `String`. + * Expression syntax is not supported within the Literal Editor for the `String` data type. +* The Variable Editor is available for [InputOutput][] and [Output][] properties where the data type is `String`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [Char][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +* [System.String][] + +[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" >}} + +[Char]: {{< url path="Cortex.Reference.DataTypes.Text.Char.MainDoc" >}} + +[System.String]: {{< url path="MSDocs.DotNet.Api.System.String.MainDoc" >}} +[String.Concat]: {{< url path="MSDocs.DotNet.Api.System.String.Concat" >}} +[String Concatenation Operator]: {{< url path="MSDocs.DotNet.Api.System.String.ConcatOperator" >}} +[String Interpolation]: {{< url path="MSDocs.DotNet.Api.System.String.StringInterpolation" >}} +[String.Format]: {{< url path="MSDocs.DotNet.Api.System.String.Format" >}} +[String.Insert]: {{< url path="MSDocs.DotNet.Api.System.String.Insert" >}} +[String.Join]: {{< url path="MSDocs.DotNet.Api.System.String.Join" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/stringcomparer.md b/content/en/docs/2024.9/Reference/data-types/text/stringcomparer.md new file mode 100644 index 000000000..470dffd7b --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/stringcomparer.md @@ -0,0 +1,151 @@ +--- +title: "StringComparer" +linkTitle: "StringComparer" +description: "Used to compare two pieces of text against each other." +weight: 1 +--- + +# {{% param title %}} + +

(System.StringComparer)

+ +## Summary + +The `StringComparer` data type is used to compare two pieces of text against each other. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `StringComparer` | +| **Full Name:** | `System.StringComparer` | +| **Alias:** | N/A | +| **Description:** | Used to compare two pieces of text against each other. | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | `IComparer`, `IComparer`, `IEqualityComparer`, `IEqualityComparer` | + +## Properties + +### CurrentCulture + +| | | +|-|-| +| **Name:** | CurrentCulture | +| **Value:** | `StringComparer.CurrentCulture` | +| **Notes:** | Gets a `StringComparer` that performs a case-sensitive text comparison using [Current Culture][CurrentCulture] rules. | + +### CurrentCultureIgnoreCase + +| | | +|-|-| +| **Name:** | CurrentCultureIgnoreCase | +| **Value:** | `StringComparer.CurrentCultureIgnoreCase` | +| **Notes:** | Gets a `StringComparer` that performs a case-insensitive text comparison using [Current Culture Ignore Case][CurrentCultureIgnoreCase] rules. | + +### InvariantCulture + +| | | +|-|-| +| **Name:** | InvariantCulture | +| **Value:** | `StringComparer.InvariantCulture` | +| **Notes:** | Gets a `StringComparer` that performs a case-sensitive text comparison using [Invariant Culture][InvariantCulture] rules. | + +### InvariantCultureIgnoreCase + +| | | +|-|-| +| **Name:** | InvariantCultureIgnoreCase | +| **Value:** | `StringComparer.InvariantCultureIgnoreCase` | +| **Notes:** | Gets a `StringComparer` that performs a case-insensitive text comparison using [Invariant Culture Ignore Case][InvariantCultureIgnoreCase] rules. | + +### Ordinal + +| | | +|-|-| +| **Name:** | Ordinal | +| **Value:** | `StringComparer.Ordinal` | +| **Notes:** | Gets a `StringComparer` that performs a case-sensitive text comparison using [Ordinal][] rules. | + +### OrdinalIgnoreCase + +| | | +|-|-| +| **Name:** | OrdinalIgnoreCase | +| **Value:** | `StringComparer.OrdinalIgnoreCase` | +| **Notes:** | Gets a `StringComparer` that performs a case-insensitive text comparison using [Ordinal Ignore Case][OrdinalIgnoreCase] rules. | + +## Remarks + +### Create a StringComparer + +The following table shows some of the ways that `StringComparer` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `StringComparer` literal | `StringComparer.CurrentCulture` | `StringComparer.CurrentCulture` | Expression | Gets a `StringComparer` that performs a case-sensitive text comparison using [Current Culture][CurrentCulture] rules. | +|| `StringComparer.CurrentCultureIgnoreCase` | `StringComparer.CurrentCultureIgnoreCase` | Expression | Gets a `StringComparer` that performs a case-insensitive text comparison using [Current Culture Ignore Case][CurrentCultureIgnoreCase] rules. | +|| `StringComparer.InvariantCulture` | `StringComparer.InvariantCulture` | Expression | Gets a `StringComparer` that performs a case-sensitive text comparison using [Invariant Culture][InvariantCulture] rules. | +|| `StringComparer.InvariantCultureIgnoreCase` | `StringComparer.InvariantCultureIgnoreCase` | Expression | Gets a `StringComparer` that performs a case-insensitive text comparison using [Invariant Culture Ignore Case][InvariantCultureIgnoreCase] rules. | +|| `StringComparer.Ordinal` | `StringComparer.Ordinal` | Expression | Gets a `StringComparer` that performs a case-sensitive text comparison using [Ordinal][] rules. | +|| `StringComparer.OrdinalIgnoreCase` | `StringComparer.OrdinalIgnoreCase` | Expression | Gets a `StringComparer` that performs a case-insensitive text comparison using [Ordinal Ignore Case][OrdinalIgnoreCase] rules. | + +### Convert StringComparer to Text + +The following table shows some of the ways that a `StringComparer` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `StringComparer.CurrentCulture.ToString()` | `"System.CultureAwareComparer"` | Expression | See [Object.ToString][] | +|| `StringComparer.CurrentCultureIgnoreCase.ToString()` | `"System.CultureAwareComparer"` | Expression | See [Object.ToString][] | +|| `StringComparer.InvariantCulture.ToString()` | `"System.CultureAwareComparer"` | Expression | See [Object.ToString][] | +|| `StringComparer.InvariantCultureIgnoreCase.ToString()` | `"System.CultureAwareComparer"` | Expression | See [Object.ToString][] | +|| `StringComparer.Ordinal.ToString()` | `"System.OrdinalCaseSensitiveComparer"` | Expression | See [Object.ToString][] | +|| `StringComparer.OrdinalIgnoreCase.ToString()` | `"System.OrdinalIgnoreCaseComparer"` | Expression | See [Object.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `StringComparer.CurrentCulture` | `"System.CultureAwareComparer"` | Expression | See [Convert Object To Text][] | +|| where `Object` property has a value of `StringComparer.CurrentCultureIgnoreCase` | `"System.CultureAwareComparer"` | Expression | See [Convert Object To Text][] | +|| where `Object` property has a value of `StringComparer.InvariantCulture` | `"System.CultureAwareComparer"` | Expression | See [Convert Object To Text][] | +|| where `Object` property has a value of `StringComparer.InvariantCultureIgnoreCase` | `"System.CultureAwareComparer"` | Expression | See [Convert Object To Text][] | +|| where `Object` property has a value of `StringComparer.Ordinal` | `"System.OrdinalCaseSensitiveComparer"` | Expression | See [Convert Object To Text][] | +|| where `Object` property has a value of `StringComparer.OrdinalIgnoreCase` | `"System.OrdinalIgnoreCaseComparer"` | Expression | See [Convert Object To Text][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `StringComparer`. +- The Literal Editor is not available for [Input][] properties where the data type is `StringComparer`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `StringComparer`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [IComparer<TPriority>][IComparer] + +### Related Concepts + +- [Working With Text][Working With Text] + +### External Documentation + +- [StringComparer][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[IComparer]: {{< url path="Cortex.Reference.DataTypes.Collections.IComparer.MainDoc" >}} +[StringComparer]: {{< url path="MSDocs.DotNet.Api.System.StringComparer" >}} + +[Working With Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[CurrentCulture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.CurrentCulture" >}} +[CurrentCultureIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.CurrentCultureIgnoreCase" >}} +[InvariantCulture]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.InvariantCulture" >}} +[InvariantCultureIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.InvariantCultureIgnoreCase" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal">}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase">}} + +[Object.ToString]: {{< url path="MSDocs.DotNet.Api.System.Object.ToString" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/text/stringcomparison.md b/content/en/docs/2024.9/Reference/data-types/text/stringcomparison.md new file mode 100644 index 000000000..c162595ef --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/stringcomparison.md @@ -0,0 +1,76 @@ +--- +title: "StringComparison" +linkTitle: "StringComparison" +description: "Used to indicate how two pieces of text are compared against each other (i.e. which culture to use and whether to consider case or not)." +weight: 1 +--- + +# {{% param title %}} + +

(System.StringComparison)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `StringComparison` data type is used to indicate how two pieces of text are compared against each other (i.e. which culture to use and whether to consider case or not). + +`StringComparison` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `StringComparison` | +| **Full Name:** | `System.StringComparison` | +| **Alias:** | N/A | +| **Description:** | Used to indicate how two pieces of text are compared against each other (i.e. which culture to use and whether to consider case or not). | +| **Default Value:** | `(StringComparison)0` | +| **Can be used as:** | `StringComparison`, `object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)StringComparison.CurrentCulture` or `(System.Int16)StringComparison.CurrentCulture` or `(short)StringComparison.CurrentCulture`) | +| | `Int32` (e.g. `(Int32)StringComparison.CurrentCulture` or `(System.Int32)StringComparison.CurrentCulture` or `(int)StringComparison.CurrentCulture`) | +| | `Int64` (e.g. `(Int64)StringComparison.CurrentCulture` or `(System.Int64)StringComparison.CurrentCulture` or `(long)StringComparison.CurrentCulture`) | +| | `Single` (e.g. `(Single)StringComparison.CurrentCulture` or `(System.Single)StringComparison.CurrentCulture` or `(float)StringComparison.CurrentCulture`) | +| | `Double` (e.g. `(Double)StringComparison.CurrentCulture` or `(System.Double)StringComparison.CurrentCulture` or `(double)StringComparison.CurrentCulture`) | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `StringComparison`. +- The Literal Editor is available for [Input][] properties where the data type is `StringComparison`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `StringComparison`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [StringComparer][] + +### Related Concepts + +- [Working With Text][] +- [Working With Enums][] + +### External Documentation + +- [System.StringComparison][StringComparison] +- [System.Enum][] + +[Working With Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} + +[StringComparer]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparer.MainDoc" >}} +[StringComparison]: {{< url path="MSDocs.DotNet.Api.System.StringComparison" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/stringsplitoptions.md b/content/en/docs/2024.9/Reference/data-types/text/stringsplitoptions.md new file mode 100644 index 000000000..1325f13fa --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/stringsplitoptions.md @@ -0,0 +1,179 @@ +--- +title: "StringSplitOptions" +linkTitle: "StringSplitOptions" +description: "Used to specify settings for splitting text (i.e. whether to include or remove empty entries from results)." +weight: 1 +--- + +# {{% param title %}} + +

(System.StringSplitOptions)

+ +## Summary + +The `StringSplitOptions` is used to specify settings for splitting text (i.e. whether to include or remove empty entries from results). + +`StringSplitOptions` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `StringSplitOptions` | +| **Full Name:** | `System.StringSplitOptions` | +| **Alias:** | N/A | +| **Description:** | Specifies settings for splitting text (i.e. whether to include or remove empty entries from results). | +| **Default Value:** | `(StringSplitOptions)0` | +| **Can be used as:** | `StringSplitOptions`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)StringSplitOptions.None` or `(System.Int16)StringSplitOptions.None` or `(short)StringSplitOptions.None`) | +| | `Int32` (e.g. `(Int32)StringSplitOptions.None` or `(System.Int32)StringSplitOptions.None` or `(int)StringSplitOptions.None`) | +| | `Int64` (e.g. `(Int64)StringSplitOptions.None` or `(System.Int64)StringSplitOptions.None` or `(long)StringSplitOptions.None`) | +| | `Single` (e.g. `(Single)StringSplitOptions.None` or `(System.Single)StringSplitOptions.None` or `(float)StringSplitOptions.None`) | +| | `Double` (e.g. `(Double)StringSplitOptions.None` or `(System.Double)StringSplitOptions.None` or `(double)StringSplitOptions.None`) | + +## Values + +### None + +| | | +|-|-| +| **Name:** | None | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Empty entries and trailing or leading whitespaces (at the start or end of text) are not removed. | + +### RemoveEmptyEntries + +| | | +|-|-| +| **Name:** | RemoveEmptyEntries | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Empty entries are removed but trailing or leading whitespaces (at the start or end of text) are not removed. | + +### TrimEntries + +| | | +|-|-| +| **Name:** | TrimEntries | +| **Value:** | [Int32][] with value `2` | +| **Notes:** | Empty entries are not removed but trailing or leading whitespaces (at the start or end of text) are removed. | + +## Remarks + +### Create StringSplitOptions + +The following table shows some of the ways that `StringSplitOptions` can be created using the expression editor. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `StringSplitOptions` literal | `None` | `StringSplitOptions.None` | Literal | Empty entries are not removed. | +| | `RemoveEmptyEntries` | `StringSplitOptions.RemoveEmptyEntries` | Literal | Empty entries are removed. | +| | `TrimEntries` | `StringSplitOptions.TrimEntries` | Literal | Empty entries are not removed but trailing and leading whitespaces are removed. | +| Use a `StringSplitOptions` expression | `StringSplitOptions.None` | `StringSplitOptions.None`| Expression | Empty entries are not removed.| +| | `StringSplitOptions.RemoveEmptyEntries` | `StringSplitOptions.RemoveEmptyEntries`| Expression | Empty entries are removed. | +| | `StringSplitOptions.TrimEntries` | `StringSplitOptions.TrimEntries`| Expression | Empty entries are not removed but trailing and leading whitespaces are removed. | +| | `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | Expression | Empty entries are removed and trailing and leading whitespaces are removed. | +| Use [Explicit Casting][] | `(StringSplitOptions)0` | `StringSplitOptions.None`| Expression | Empty entries are not removed. | +| | `(StringSplitOptions)1` | `StringSplitOptions.RemoveEmptyEntries`| Expression | Empty entries are removed. | +| | `(StringSplitOptions)2` | `StringSplitOptions.TrimEntries`| Expression | Empty entries are not removed but trailing and leading whitespaces are removed. | +| | `(StringSplitOptions)3` | `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries`| Expression | Empty entries are removed and trailing and leading whitespaces are removed. | +| Use `Enum.Parse` | `(StringSplitOptions)Enum.Parse(typeof(StringSplitOptions), "None")` | `StringSplitOptions.None`| Expression | Parses `"None"` and converts it to `StringSplitOptions.None`. See [Enum.Parse][] | +| | `(StringSplitOptions)Enum.Parse(typeof(StringSplitOptions), "RemoveEmptyEntries")` | `StringSplitOptions.RemoveEmptyEntries`| Expression | Parses `"RemoveEmptyEntries"` and converts it to `StringSplitOptions.RemoveEmptyEntries`. See [Enum.Parse][] | +| | `(StringSplitOptions)Enum.Parse(typeof(StringSplitOptions), "TrimEntries")` | `StringSplitOptions.TrimEntries`| Expression | Parses `"TrimEntries"` and converts it to `StringSplitOptions.TrimEntries`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(StringSplitOptions)Enum.ToObject(typeof(StringSplitOptions), 0)` | `StringSplitOptions.None`| Expression | Converts `0` to `StringSplitOptions.None` value. See [Enum.ToObject][] | +| | `(StringSplitOptions)Enum.ToObject(typeof(StringSplitOptions), 1)` | `StringSplitOptions.RemoveEmptyEntries`| Expression | Converts `1` to `StringSplitOptions.RemoveEmptyEntries` value. See [Enum.ToObject][] | +| | `(StringSplitOptions)Enum.ToObject(typeof(StringSplitOptions), 2)` | `StringSplitOptions.TrimEntries`| Expression | Converts `2` to `StringSplitOptions.TrimEntries` value. See [Enum.ToObject][] | +| | `(StringSplitOptions)Enum.ToObject(typeof(StringSplitOptions), 3)` | `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | Expression | Converts `3` to `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` value. See [Enum.ToObject][] | + + +Please see [Instantiating an enumeration type][] for further information. + +### Convert StringSplitOptions to Text + +The following table shows some of the ways that a `StringSplitOptions` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `StringSplitOptions.None.ToString()` | `"None"` | Expression | Converts `StringSplitOptions.None` to `"None"`. See [Enum.ToString][] | +| | `StringSplitOptions.RemoveEmptyEntries.ToString()` | `"RemoveEmptyEntries"` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries` to `"RemoveEmptyEntries"`. See [Enum.ToString][] | +| | `StringSplitOptions.TrimEntries.ToString()` | `"TrimEntries"` | Expression | Converts `StringSplitOptions.TrimEntries` to `"TrimEntries"`. See [Enum.ToString][] | +| | `(StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries).ToString()` | `"RemoveEmptyEntries, TrimEntries"` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `"RemoveEmptyEntries, TrimEntries"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(StringSplitOptions.None)` | `"None"` | Expression | Converts `StringSplitOptions.None` to `"None"`. See [Convert.ToString][] | +| | `Convert.ToString(StringSplitOptions.RemoveEmptyEntries)` | `"RemoveEmptyEntries"` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries` to `"RemoveEmptyEntries"`. See [Convert.ToString][] | +| | `Convert.ToString(StringSplitOptions.TrimEntries)` | `"TrimEntries"` | Expression | Converts `StringSplitOptions.TrimEntries` to `"TrimEntries"`. See [Convert.ToString][] | +| | `Convert.ToString(StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries)` | `"RemoveEmptyEntries, TrimEntries"` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `"RemoveEmptyEntries, TrimEntries"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `StringSplitOptions.None` | `"None"` | N/A | Converts `StringSplitOptions.None` to `"None"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `StringSplitOptions.RemoveEmptyEntries` | `"RemoveEmptyEntries"` | N/A | Converts `StringSplitOptions.RemoveEmptyEntries` to `"RemoveEmptyEntries"`. See [Convert Object To Text][] || | where `Object` property has a value of `StringSplitOptions.RemoveEmptyEntries` | `"RemoveEmptyEntries"` | N/A | |Converts `StringSplitOptions.RemoveEmptyEntries` to `"RemoveEmptyEntries"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `StringSplitOptions.TrimEntries` | `"TrimEntries"` | N/A | Converts `StringSplitOptions.TrimEntries` to `"TrimEntries"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | `"RemoveEmptyEntries, TrimEntries"` | N/A | Converts `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `"RemoveEmptyEntries, TrimEntries"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `StringSplitOptions.None` | `"0"` | N/A | Converts `StringSplitOptions.None` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `StringSplitOptions.RemoveEmptyEntries` | `"1"` | N/A | Converts `StringSplitOptions.RemoveEmptyEntries` to `"1"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `StringSplitOptions.TrimEntries` | `"2"` | N/A | Converts `StringSplitOptions.TrimEntries` to `"2"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` | `"3"` | N/A | Converts `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `"3"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert StringSplitOptions to a Number + +The following table shows some of the ways that a `StringSplitOptions` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)StringSplitOptions.None` | `0` | Expression | [Casts][Explicit Casting] `StringSplitOptions.None` to `0` | +| | `(Int32)StringSplitOptions.RemoveEmptyEntries` | `1` | Expression | [Casts][Explicit Casting] `StringSplitOptions.RemoveEmptyEntries` to `1` | +| | `(Int32)StringSplitOptions.TrimEntries` | `2` | Expression | [Casts][Explicit Casting] `StringSplitOptions.TrimEntries` to `2` | +| | `(Int32)(StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries)` | `3` | Expression | [Casts][Explicit Casting] `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `3` | +| Use `Convert.ToInt32` | `Convert.ToInt32(StringSplitOptions.None)` | `0` | Expression | Converts `StringSplitOptions.None` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(StringSplitOptions.RemoveEmptyEntries)` | `1` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries` to `1`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(StringSplitOptions.TrimEntries)` | `2` | Expression | Converts `StringSplitOptions.TrimEntries` to `2`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries)` | `3` | Expression | Converts `StringSplitOptions.RemoveEmptyEntries \| StringSplitOptions.TrimEntries` to `3`. See [Convert.ToInt32][] | + +### Property Editor Support + +* The Expression Editor is available for [Input][] properties where the data type is `StringSplitOptions`. +* The Literal Editor is available for [Input][] properties where the data type is `StringSplitOptions`. +* The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `StringSplitOptions`. + +### Known Limitations + +Currently it's not possible to specify settings to both trim text and remove empty whitespaces using the Literal Editor. This can be done using the Expression Editor; see the last example in "Use a `StringSplitOptions` expression" in the [Create StringSplitOptions][StringSplitOptions Property] table. + +## See Also + +### Related Data Types + +* [Int32][] +* [String][] + +### Related Concepts + +* [Working with Enums][] +* [Explicit Casting][] + +### External Documentation + +* [StringSplitOptions][] + +[Split Text]: {{< url path="Cortex.Reference.Blocks.Text.SplitText.SplitText.MainDoc" >}} + +[StringSplitOptions Property]: {{< ref "#create-stringsplitoptions" >}} + +[StringSplitOptions]: {{< url path="MSDocs.DotNet.Api.System.StringSplitOptions" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} + diff --git a/content/en/docs/2024.9/Reference/data-types/text/textdecodingerrorcode.md b/content/en/docs/2024.9/Reference/data-types/text/textdecodingerrorcode.md new file mode 100644 index 000000000..7a40a1c8a --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/textdecodingerrorcode.md @@ -0,0 +1,168 @@ +--- +title: "TextDecodingErrorCode" +linkTitle: "TextDecodingErrorCode" +description: "Used to represent an error code explaining the reason an `TextDecodingException` occurred." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Encoding.TextDecodingErrorCode)

+ +## Summary + +The `TextDecodingErrorCode` data type is used to represent an error code explaining the reason a [TextDecodingException][] occurred. For more information on the exception itself, see [TextDecodingException][]. + +`TextDecodingErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `TextDecodingErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Text.Encoding.TextDecodingErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [TextDecodingException][] occurred. | +| **Default Value:** | `(TextDecodingErrorCode)0` | +| **Can be used as:** | `TextDecodingErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)TextDecodingErrorCode.Base64InvalidCharacter` or `(System.Int16)TextDecodingErrorCode.Base64InvalidCharacter` or `(short)TextDecodingErrorCode.Base64InvalidCharacter`) | +| | `Int32` (e.g. `(Int32)TextDecodingErrorCode.Base64InvalidCharacter` or `(System.Int32)TextDecodingErrorCode.Base64InvalidCharacter` or `(int)TextDecodingErrorCode.Base64InvalidCharacter`) | +| | `Int64` (e.g. `(Int64)TextDecodingErrorCode.Base64InvalidCharacter` or `(System.Int64)TextDecodingErrorCode.Base64InvalidCharacter` or `(long)TextDecodingErrorCode.Base64InvalidCharacter`) | +| | `Single` (e.g. `(Single)TextDecodingErrorCode.Base64InvalidCharacter` or `(System.Single)TextDecodingErrorCode.Base64InvalidCharacter` or `(float)TextDecodingErrorCode.Base64InvalidCharacter`) | +| | `Double` (e.g. `(Double)TextDecodingErrorCode.Base64InvalidCharacter` or `(System.Double)TextDecodingErrorCode.Base64InvalidCharacter` or `(double)TextDecodingErrorCode.Base64InvalidCharacter`) | + +## Values + +### Base64InvalidCharacter + +| | | +|-|-| +| **Name:** | Base64InvalidCharacter | +| **Value:** | [Int32][] with value `100` | +| **Notes:** | Used when a [TextDecodingException][] occurred due to the provided text containing one or more invalid characters. See [Invalid Base64 character][InvalidBase64]. | + +### HexOddNumberOfCharacters + +| | | +|-|-| +| **Name:** | HexOddNumberOfCharacters | +| **Value:** | [Int32][] with value `300` | +| **Notes:** | Used when a [TextDecodingException][] occurred due to the provided text containing an odd number of characters. See [Odd number of characters using Hex][InvalidHex]. | + +### Base64UrlInvalidCharacter + +| | | +|-|-| +| **Name:** | Base64UrlInvalidCharacter | +| **Value:** | [Int32][] with value `600` | +| **Notes:** | Used when a [TextDecodingException][] occurred due to the provided text containing one or more invalid characters. See [Invalid Base64Url character][InvalidBase64Url]. | + +## Remarks + +### Create a TextDecodingErrorCode + +The following table shows some of the ways that `TextDecodingErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TextDecodingErrorCode` expression | `TextDecodingErrorCode.Base64InvalidCharacter` | `TextDecodingErrorCode.Base64InvalidCharacter`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing one or more characters that are invalid in [Base64][] encoded text. | +| | `TextDecodingErrorCode.HexOddNumberOfCharacters` | `TextDecodingErrorCode.HexOddNumberOfCharacters`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing an odd number of characters which is invalid for [Hex][] encoded text. | +| | `TextDecodingErrorCode.Base64UrlInvalidCharacter` | `TextDecodingErrorCode.Base64UrlInvalidCharacter`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing one or more characters that are invalid in [Base64Url][] encoded text. | +| Use [Explicit Casting][] | `(TextDecodingErrorCode)100` | `TextDecodingErrorCode.Base64InvalidCharacter`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing one or more characters that are invalid in [Base64][] encoded text. | +| | `(TextDecodingErrorCode)300` | `TextDecodingErrorCode.HexOddNumberOfCharacters`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing an odd number of characters which is invalid for [Hex][] encoded text. | +| | `(TextDecodingErrorCode)600` | `TextDecodingErrorCode.Base64UrlInvalidCharacter`| Expression | Indicates a [TextDecodingException][] occurred due to the text provided containing one or more characters that are invalid in [Base64Url][] encoded text. | +| Use `Enum.Parse` | `(TextDecodingErrorCode)Enum.Parse(typeof(TextDecodingErrorCode), "Base64InvalidCharacter")` | `TextDecodingErrorCode.Base64InvalidCharacter`| Expression | Parses `"Base64InvalidCharacter"` and converts it to `TextDecodingErrorCode.Base64InvalidCharacter`. See [Enum.Parse][] | +| | `(TextDecodingErrorCode)Enum.Parse(typeof(TextDecodingErrorCode), "HexOddNumberOfCharacters")` | `TextDecodingErrorCode.HexOddNumberOfCharacters`| Expression | Parses `"HexOddNumberOfCharacters"` and converts it to `TextDecodingErrorCode.HexOddNumberOfCharacters`. See [Enum.Parse][] | +| | `(TextDecodingErrorCode)Enum.Parse(typeof(TextDecodingErrorCode), "Base64UrlInvalidCharacter)` | `TextDecodingErrorCode.Base64UrlInvalidCharacter`| Expression | Parses `"Base64UrlInvalidCharacter"` and converts it to `TextDecodingErrorCode.Base64UrlInvalidCharacer`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(TextDecodingErrorCode)Enum.ToObject(typeof(TextDecodingErrorCode), 100)` | `TextDecodingErrorCode.Base64InvalidCharacter`| Expression | Converts `100` to `TextDecodingErrorCode.Base64InvalidCharacter` value. See [Enum.ToObject][] | +| | `(TextDecodingErrorCode)Enum.ToObject(typeof(TextDecodingErrorCode), 300)` | `TextDecodingErrorCode.HexOddNumberOfCharacters`| Expression | Converts `300` to `TextDecodingErrorCode.HexOddNumberOfCharacters` value. See [Enum.ToObject][] | +| | `(TextDecodingErrorCode)Enum.ToObject(typeof(TextDecodingErrorCode), 600)` | `TextDecodingErrorCode.Base64UrlInvalidCharacter`| Expression | Converts `600` to `TextDecodingErrorCode.Base64UrlInvalidCharacter` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert TextDecodingErrorCode to Text + +The following table shows some of the ways that a `TextDecodingErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `TextDecodingErrorCode.Base64InvalidCharacter.ToString()` | `"Base64InvalidCharacter"` | Expression | Converts `TextDecodingErrorCode.Base64InvalidCharacter` to `"Base64InvalidCharacter"`. See [Enum.ToString][] | +| | `TextDecodingErrorCode.HexOddNumberOfCharacters.ToString()` | `"HexOddNumberOfCharacters"` | Expression | Converts `TextDecodingErrorCode.HexOddNumberOfCharacters` to `"HexOddNumberOfCharacters"`. See [Enum.ToString][] | +| | `TextDecodingErrorCode.Base64UrlInvalidCharacter.ToString()` | `"Base64UrlInvalidCharacter"` | Expression | Converts `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `"Base64UrlInvalidCharacter"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(TextDecodingErrorCode.Base64InvalidCharacter)` | `"Base64InvalidCharacter"` | Expression | Converts `TextDecodingErrorCode.Base64InvalidCharacter` to `"Base64InvalidCharacter"`. See [Convert.ToString][] | +| | `Convert.ToString(TextDecodingErrorCode.HexOddNumberOfCharacters)` | `"HexOddNumberOfCharacters"` | Expression | Converts `TextDecodingErrorCode.HexOddNumberOfCharacters` to `"HexOddNumberOfCharacters"`. See [Convert.ToString][] | +| | `Convert.ToString(TextDecodingErrorCode.Base64UrlInvalidCharacter)` | `"Base64UrlInvalidCharacter"` | Expression | Converts `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `"Base64UrlInvalidCharacter"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `TextDecodingErrorCode.Base64InvalidCharacter` | `"Base64InvalidCharacter"` | N/A | Converts `TextDecodingErrorCode.Base64InvalidCharacter` to `"Base64InvalidCharacter"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextDecodingErrorCode.HexOddNumberOfCharacters` | `"HexOddNumberOfCharacters"` | N/A | Converts `TextDecodingErrorCode.HexOddNumberOfCharacters` to `"HexOddNumberOfCharacters"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextDecodingErrorCode.Base64UrlInvalidCharacter` | `"Base64UrlInvalidCharacter"` | N/A | Converts `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `"Base64UrlInvalidCharacter"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `TextDecodingErrorCode.Base64InvalidCharacter` | `"100"` | N/A | Converts `TextDecodingErrorCode.Base64InvalidCharacter` to `"100"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextDecodingErrorCode.HexOddNumberOfCharacters` | `"300"` | N/A | Converts `TextDecodingErrorCode.HexOddNumberOfCharacters` to `"300"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextDecodingErrorCode.Base64UrlInvalidCharacter` | `"600"` | N/A | Converts `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `"600"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert TextDecodingErrorCode to a Number + +The following table shows some of the ways that a `TextDecodingErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)TextDecodingErrorCode.Base64InvalidCharacter` | `100` | Expression | [Casts][Explicit Casting] `TextDecodingErrorCode.Base64InvalidCharacter` to `100` | +| | `(Int32)TextDecodingErrorCode.HexOddNumberOfCharacters` | `300` | Expression | [Casts][Explicit Casting] `TextDecodingErrorCode.HexOddNumberOfCharacters` to `300` | +| | `(Int32)TextDecodingErrorCode.Base64UrlInvalidCharacter` | `600` | Expression | [Casts][Explicit Casting] `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `600` | +| Use `Convert.ToInt32` | `Convert.ToInt32(TextDecodingErrorCode.Base64InvalidCharacter)` | `100` | Expression | Converts `TextDecodingErrorCode.Base64InvalidCharacter` to `100`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextDecodingErrorCode.HexOddNumberOfCharacters)` | `300` | Expression | Converts `TextDecodingErrorCode.HexOddNumberOfCharacters` to `300`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextDecodingErrorCode.Base64UrlInvalidCharacter)` | `600` | Expression | Converts `TextDecodingErrorCode.Base64UrlInvalidCharacter` to `600`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TextDecodingErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `TextDecodingErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TextDecodingErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [TextDecodingException][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working with Text][WorkingWithText] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[TextDecodingException]: {{< url path="Cortex.Reference.Exceptions.Text.Encoding.TextDecodingException.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" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[WorkingWithText]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[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" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/textencodingformat.md b/content/en/docs/2024.9/Reference/data-types/text/textencodingformat.md new file mode 100644 index 000000000..3734deab7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/textencodingformat.md @@ -0,0 +1,222 @@ +--- +title: "TextEncodingFormat" +linkTitle: "TextEncodingFormat" +description: "Used to represent formats available for encoding and decoding text." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Encoding.TextEncodingFormat)

+ +## Summary + +The `TextEncodingFormat` data type is used to represent formats available for encoding and decoding text. + +`TextEncodingFormat` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `TextEncodingFormat` | +| **Full Name:** | `Cortex.DataTypes.Text.Encoding.TextEncodingFormat` | +| **Alias:** | N/A | +| **Description:** | The encoding format used while encoding/decoding text. | +| **Default Value:** | `(TextEncodingFormat)0` | +| **Can be used as:** | `TextEncodingFormat`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)TextEncodingFormat.Base64` or `(System.Int16)TextEncodingFormat.Base64` or `(short)TextEncodingFormat.Base64`) | +| | `Int32` (e.g. `(Int32)TextEncodingFormat.Base64` or `(System.Int32)TextEncodingFormat.Base64` or `(int)TextEncodingFormat.Base64`) | +| | `Int64` (e.g. `(Int64)TextEncodingFormat.Base64` or `(System.Int64)TextEncodingFormat.Base64` or `(long)TextEncodingFormat.Base64`) | +| | `Single` (e.g. `(Single)TextEncodingFormat.Base64` or `(System.Single)TextEncodingFormat.Base64` or `(float)TextEncodingFormat.Base64`) | +| | `Double` (e.g. `(Double)TextEncodingFormat.Base64` or `(System.Double)TextEncodingFormat.Base64` or `(double)TextEncodingFormat.Base64`) | + +## Values + +### Base64 + +| | | +|-|-| +| **Name:** | Base64 | +| **Value:** | [Int32][] with value `0` | +| **Notes:** | Base64 encoding format. | + +### Url + +| | | +|-|-| +| **Name:** | Url | +| **Value:** | [Int32][] with value `1` | +| **Notes:** | Url encoding format. | + +### Hex + +| | | +|-|-| +| **Name:** | Hex | +| **Value:** | [Int32][] with value `2` | +| **Notes:** | Hex (Hexadecimal) encoding format. | + +### Html + +| | | +|-|-| +| **Name:** | Html | +| **Value:** | [Int32][] with value `3` | +| **Notes:** | Html encoding format. | + +### Utf8 + +| | | +|-|-| +| **Name:** | Utf8 | +| **Value:** | [Int32][] with value `4` | +| **Notes:** | Utf8 encoding format. | + +### Base64Url + +| | | +|-|-| +| **Name:** | Base64Url | +| **Value:** | [Int32][] with value `5` | +| **Notes:** | Base64Url encoding format.| + +## Remarks + +### Creating a TextEncodingFormat + +The following table shows some of the ways that `TextEncodingFormat` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Declare a `TextEncodingFormat` literal | `Base64` | `TextEncodingFormat.Text`| Literal | Used when encoding to Base64. | +| | `Url` | `TextEncodingFormat.Url`| Literal | Used when encoding to Url. | +| | `Hex` | `TextEncodingFormat.Hex`| Literal | Used when encoding to Hex. | +| | `Html` | `TextEncodingFormat.Html`| Literal | Used when encoding to Html. | +| | `Utf8` | `TextEncodingFormat.Utf8`| Literal | Used when encoding to Utf8. | +| | `Base64Url` | `TextEncodingFormat.Base64Url`| Literal | Used when encoding to Base64Url. | +| Use a `TextEncodingFormat` expression | `TextEncodingFormat.Base64` | `TextEncodingFormat.Base64`| Expression | Used when encoding to Base64.| +| | `TextEncodingFormat.Url` | `TextEncodingFormat.Url`| Expression | Used when encoding to Url. | +| | `TextEncodingFormat.Hex` | `TextEncodingFormat.Hex`| Expression | Used when encoding to Hex. | +| | `TextEncodingFormat.Html` | `TextEncodingFormat.Html`| Expression | Used when encoding to Html. | +| | `TextEncodingFormat.Utf8` | `TextEncodingFormat.Utf8`| Expression | Used when encoding to Utf8. | +| | `TextEncodingFormat.Base64Url` | `TextEncodingFormat.Base64Url`| Expression | Used when encoding to Base64Url. | +| Use [Explicit Casting][] | `(TextEncodingFormat)0` | `TextEncodingFormat.Base64`| Expression | Used when encoding to Base64. | +| | `(TextEncodingFormat)1` | `TextEncodingFormat.Url`| Expression | Used when encoding to Url. | +| | `(TextEncodingFormat)2` | `TextEncodingFormat.Hex`| Expression | Used when encoding to Hex. | +| | `(TextEncodingFormat)3` | `TextEncodingFormat.Html`| Expression | Used when encoding to Html. | +| | `(TextEncodingFormat)4` | `TextEncodingFormat.Utf8`| Expression | Used when encoding to Utf8. | +| | `(TextEncodingFormat)5` | `TextEncodingFormat.Base64Url`| Expression | Used when encoding to Base64Url. | +| Use `Enum.Parse` | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Base64")` | `TextEncodingFormat.Base64`| Expression | Parses `"Base64"` and converts it to `TextEncodingFormat.Base64`. See [Enum.Parse][] | +| | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Url")` | `TextEncodingFormat.Url`| Expression | Parses `"Url"` and converts it to `TextEncodingFormat.Url`. See [Enum.Parse][] | +| | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Hex")` | `TextEncodingFormat.Hex`| Expression | Parses `"Hex"` and converts it to `TextEncodingFormat.Hex`. See [Enum.Parse][] | +| | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Html")` | `TextEncodingFormat.Html`| Expression | Parses `"Html"` and converts it to `TextEncodingFormat.Html`. See [Enum.Parse][] | +| | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Utf8")` | `TextEncodingFormat.Utf8`| Expression | Parses `"Utf8"` and converts it to `TextEncodingFormat.Utf8`. See [Enum.Parse][] | +| | `(TextEncodingFormat)Enum.Parse(typeof(TextEncodingFormat), "Base64Url")` | `TextEncodingFormat.Base64Url`| Expression | Parses `"Base64Url"` and converts it to `TextEncodingFormat.Base64Url`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 0)` | `TextEncodingFormat.Base64`| Expression | Converts `0` to `TextEncodingFormat.Base64` value. See [Enum.ToObject][] | +| | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 1)` | `TextEncodingFormat.Url`| Expression | Converts `1` to `TextEncodingFormat.Url` value. See [Enum.ToObject][] | +| | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 2)` | `TextEncodingFormat.Hex`| Expression | Converts `2` to `TextEncodingFormat.Hex` value. See [Enum.ToObject][] | +| | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 3)` | `TextEncodingFormat.Html`| Expression | Converts `3` to `TextEncodingFormat.Html` value. See [Enum.ToObject][] | +| | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 4)` | `TextEncodingFormat.Utf8`| Expression | Converts `4` to `TextEncodingFormat.Utf8` value. See [Enum.ToObject][] | +| | `(TextEncodingFormat)Enum.ToObject(typeof(TextEncodingFormat), 5)` | `TextEncodingFormat.Base64Url`| Expression | Converts `5` to `TextEncodingFormat.Base64Url` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert TextEncodingFormat to Text + +The following table shows some of the ways that a `TextEncodingFormat` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `TextEncodingFormat.Base64.ToString()` | `"Base64"` | Expression | Converts `TextEncodingFormat.Base64` to `"Base64"`. See [Enum.ToString][] | +| | `TextEncodingFormat.Url.ToString()` | `"Url"` | Expression | Converts `TextEncodingFormat.Url` to `"Url"`. See [Enum.ToString][] | +| | `TextEncodingFormat.Hex.ToString()` | `"Hex"` | Expression | Converts `TextEncodingFormat.Hex` to `"Hex"`. See [Enum.ToString][] | +| | `TextEncodingFormat.Html.ToString()` | `"Html"` | Expression | Converts `TextEncodingFormat.Html` to `"Html"`. See [Enum.ToString][] | +| | `TextEncodingFormat.Utf8.ToString()` | `"Utf8"` | Expression | Converts `TextEncodingFormat.Utf8` to `"Utf8"`. See [Enum.ToString][] | +| | `TextEncodingFormat.Base64Url.ToString()` | `"Base64Url"` | Expression | Converts `TextEncodingFormat.Base64Url` to `"Base64Url"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(TextEncodingFormat.Base64)` | `"Base64"` | Expression | Converts `TextEncodingFormat.Base64` to `"Base64"`. See [Convert.ToString][] | +| | `Convert.ToString(TextEncodingFormat.Url)` | `"Url"` | Expression | Converts `TextEncodingFormat.Url` to `"Url"`. See [Convert.ToString][] | +| | `Convert.ToString(TextEncodingFormat.Hex)` | `"Hex"` | Expression | Converts `TextEncodingFormat.Hex` to `"Hex"`. See [Convert.ToString][] | +| | `Convert.ToString(TextEncodingFormat.Html)` | `"Html"` | Expression | Converts `TextEncodingFormat.Html` to `"Html"`. See [Convert.ToString][] | +| | `Convert.ToString(TextEncodingFormat.Utf8)` | `"Utf8"` | Expression | Converts `TextEncodingFormat.Utf8` to `"Utf8"`. See [Convert.ToString][] | +| | `Convert.ToString(TextEncodingFormat.Base64Url)` | `"Base64Url"` | Expression | Converts `TextEncodingFormat.Base64Url` to `"Base64Url"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `TextEncodingFormat.Base64` | `"Base64"` | N/A | Converts `TextEncodingFormat.Base64` to `"Base64"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextEncodingFormat.Url` | `"Url"` | N/A | Converts `TextEncodingFormat.Url` to `"Url"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextEncodingFormat.Hex` | `"Hex"` | N/A | Converts `TextEncodingFormat.Hex` to `"Hex"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextEncodingFormat.Html` | `"Html"` | N/A | Converts `TextEncodingFormat.Html` to `"Html"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextEncodingFormat.Utf8` | `"Utf8"` | N/A | Converts `TextEncodingFormat.Utf8` to `"Utf8"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `TextEncodingFormat.Base64Url` | `"Base64Url"` | N/A | Converts `TextEncodingFormat.Base64Url` to `"Base64Url"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `TextEncodingFormat.Base64` | `"0"` | N/A | Converts `TextEncodingFormat.Base64` to `"0"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextEncodingFormat.Url` | `"1"` | N/A | Converts `TextEncodingFormat.Url` to `"1"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextEncodingFormat.Hex` | `"2"` | N/A | Converts `TextEncodingFormat.Hex` to `"2"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextEncodingFormat.Html` | `"3"` | N/A | Converts `TextEncodingFormat.Html` to `"3"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextEncodingFormat.Utf8` | `"4"` | N/A | Converts `TextEncodingFormat.Utf8` to `"4"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `TextEncodingFormat.Base64Url` | `"5"` | N/A | Converts `TextEncodingFormat.Base64Url` to `"5"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert TextEncodingFormat to a Number + +The following table shows some of the ways that a `TextEncodingFormat` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)TextEncodingFormat.Base64` | `0` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Base64` to `0` | +| | `(Int32)TextEncodingFormat.Url` | `1` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Url` to `1` | +| | `(Int32)TextEncodingFormat.Hex` | `2` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Hex` to `2` | +| | `(Int32)TextEncodingFormat.Html` | `3` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Html` to `3` | +| | `(Int32)TextEncodingFormat.Utf8` | `4` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Utf8` to `4` | +| | `(Int32)TextEncodingFormat.Base64Url` | `5` | Expression | [Casts][Explicit Casting] `TextEncodingFormat.Base64Url` to `5` | +| Use `Convert.ToInt32` | `Convert.ToInt32(TextEncodingFormat.Base64)` | `0` | Expression | Converts `TextEncodingFormat.Base64` to `0`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextEncodingFormat.Url)` | `1` | Expression | Converts `TextEncodingFormat.Url` to `1`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextEncodingFormat.Hex)` | `2` | Expression | Converts `TextEncodingFormat.Hex` to `2`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextEncodingFormat.Html)` | `3` | Expression | Converts `TextEncodingFormat.Html` to `3`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextEncodingFormat.Utf8)` | `4` | Expression | Converts `TextEncodingFormat.Utf8` to `4`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(TextEncodingFormat.Base64Url)` | `5` | Expression | Converts `TextEncodingFormat.Base64Url` to `5`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TextEncodingFormat`. +- The Literal Editor is available for [Input][] properties where the data type is `TextEncodingFormat`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TextEncodingFormat`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] +- [Working with Text][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} + +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/texttofind.md b/content/en/docs/2024.9/Reference/data-types/text/texttofind.md new file mode 100644 index 000000000..8ec45ad76 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/texttofind.md @@ -0,0 +1,138 @@ +--- +title: "TextToFind" +linkTitle: "TextToFind" +description: "Used to represent a search query for finding text." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.TextToFind)

+ +## Summary + +The `TextToFind` data type is used to represent a search query for finding text.

It specifies what a valid [match][Match] should start, contain and end with. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `TextToFind` | +| **Full Name:** | `Cortex.DataTypes.Text.TextToFind` | +| **Alias:** | N/A | +| **Description:** | A text to find in another text. | +| **Default Value:** | `null` | +| **Can be used as:** | `TextToFind` | +| **Can be cast to:** | N/A | + +## Properties + +### Starts With + +[Starts With][StartsWith Property] is used to define the [String][] a valid match should start with. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### Contains + +[Contains][Contains Property] is used to define the [String][] a valid match should contains between [Starts With][StartsWith Property] and [Ends With][EndsWith Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### Ends With + +[Ends With][EndsWith Property] is used to define the [String][] a valid match should end with. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +## Remarks + +### Create a TextToFind + +The following table shows some of the ways that a `TextToFind` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TextToFind` constructor | `new TextToFind(startsWith: "the", contains: "quick", endsWith: "fox")`| `{"StartsWith":"the", "Contains":"quick", "EndsWith":"fox"}` | Expression | || + +A `TextToFind` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `StartsWith` | `String` | `"the"` | [Starts With][StartsWith Property] defines the string a valid match should start with. | +| `Contains` | `String` | `"quick"` | [Contains][Contains Property] defines the string a valid match should contain. | +| `EndsWith` | `String` | `"fox"` | [Ends With][EndsWith Property] defines the string a valid match should end with. | + +### Convert TextToFind to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"StartsWith":"the", "Contains":"quick", "EndsWith":"fox"}` | `""{\r\n \"StartsWith\": \"the\",\r\n \"Contains\": \"quick\",\r\n \"EndsWith\": \"fox\"\r\n}""` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TextToFind`. +- The Literal Editor is available for [Input][] properties where the data type is `TextToFind`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TextToFind`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +None + +[Contains Property]: {{< ref "#contains" >}} +[EndsWith Property]: {{< ref "#ends-with" >}} +[StartsWith Property]: {{< ref "#starts-with" >}} + +[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" >}} + +[Char]: {{< url path="Cortex.Reference.DataTypes.Text.Char.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[System.String]: {{< url path="MSDocs.DotNet.Api.System.String.MainDoc" >}} +[String.Concat]: {{< url path="MSDocs.DotNet.Api.System.String.Concat" >}} +[String Concatenation Operator]: {{< url path="MSDocs.DotNet.Api.System.String.ConcatOperator" >}} +[String Interpolation]: {{< url path="MSDocs.DotNet.Api.System.String.StringInterpolation" >}} +[String.Format]: {{< url path="MSDocs.DotNet.Api.System.String.Format" >}} +[String.Insert]: {{< url path="MSDocs.DotNet.Api.System.String.Insert" >}} +[String.Join]: {{< url path="MSDocs.DotNet.Api.System.String.Join" >}} + +[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" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/unicodeencoding.md b/content/en/docs/2024.9/Reference/data-types/text/unicodeencoding.md new file mode 100644 index 000000000..94849a15f --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/unicodeencoding.md @@ -0,0 +1,64 @@ +--- +title: "UnicodeEncoding" +linkTitle: "UnicodeEncoding" +description: "Used to represent Unicode character encoding." +weight: 1 +--- + +# {{% param title %}} + +

(System.Text.UnicodeEncoding)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `UnicodeEncoding` data type is used to represent Unicode character encoding. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `UnicodeEncoding` | +| **Full Name:** | `System.Text.UnicodeEncoding` | +| **Alias:** | N/A | +| **Description:** | Used to represent Unicode character encoding. | +| **Default Value:** | `null` | +| **Can be used as:** | `UnicodeEncoding`, `Encoding`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `UnicodeEncoding`. +- The Literal Editor is available for [Input][] properties where the data type is `UnicodeEncoding`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `UnicodeEncoding`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Encoding][] +- [UTF32Encoding][] +- [UTF8Encoding][] + +### Related Concepts + +None + +### External Documentation + +- [System.Text.UnicodeEncoding][UnicodeEncoding] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.Encoding.MainDoc">}} +[UTF32Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF32Encoding.MainDoc">}} +[UTF8Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF8Encoding.MainDoc">}} +[UnicodeEncoding]: {{< url path = "MSDocs.DotNet.Api.System.Text.UnicodeEncoding">}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/utf32encoding.md b/content/en/docs/2024.9/Reference/data-types/text/utf32encoding.md new file mode 100644 index 000000000..dfc87a552 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/utf32encoding.md @@ -0,0 +1,64 @@ +--- +title: "UTF32Encoding" +linkTitle: "UTF32Encoding" +description: "Used to represent UTF32 character encoding." +weight: 1 +--- + +# {{% param title %}} + +

(System.Text.UTF32Encoding)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `UTF32Encoding` data type is used to represent UTF32 character encoding. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `UTF32Encoding` | +| **Full Name:** | `System.Text.UTF32Encoding` | +| **Alias:** | N/A | +| **Description:** | Used to represent UTF32 character encoding. | +| **Default Value:** | `null` | +| **Can be used as:** | `UTF32Encoding`, `Encoding`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `UTF32Encoding`. +- The Literal Editor is available for [Input][] properties where the data type is `UTF32Encoding`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `UTF32Encoding`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Encoding][] +- [UnicodeEncoding][] +- [UTF8Encoding][] + +### Related Concepts + +None + +### External Documentation + +- [System.Text.UTF32Encoding][UTF32Encoding] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.Encoding.MainDoc">}} +[UnicodeEncoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UnicodeEncoding.MainDoc">}} +[UTF8Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF8Encoding.MainDoc">}} +[UTF32Encoding]: {{< url path = "MSDocs.DotNet.Api.System.Text.Utf32Encoding">}} diff --git a/content/en/docs/2024.9/Reference/data-types/text/utf8encoding.md b/content/en/docs/2024.9/Reference/data-types/text/utf8encoding.md new file mode 100644 index 000000000..f26f239fe --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/text/utf8encoding.md @@ -0,0 +1,64 @@ +--- +title: "UTF8Encoding" +linkTitle: "UTF8Encoding" +description: "Used to represent UTF8 character encoding." +weight: 1 +--- + +# {{% param title %}} + +

(System.Text.UTF8Encoding)

+ +{{% alert type="information" title="Information" %}}Improvements to this page are planned for the future.{{% /alert %}} + +## Summary + +The `UTF8Encoding` data type is used to represent UTF8 character encoding. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `UTF8Encoding` | +| **Full Name:** | `System.Text.UTF8Encoding` | +| **Alias:** | N/A | +| **Description:** | Used to represent UTF8 character encoding. | +| **Default Value:** | `null` | +| **Can be used as:** | `UTF8Encoding`, `Encoding`, `object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Remarks + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `UTF8Encoding`. +- The Literal Editor is available for [Input][] properties where the data type is `UTF8Encoding`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `UTF8Encoding`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [Encoding][] +- [UnicodeEncoding][] +- [UTF32Encoding][] + +### Related Concepts + +None + +### External Documentation + +- [System.Text.UTF8Encoding][UTF8Encoding] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} + +[Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.Encoding.MainDoc">}} +[UnicodeEncoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UnicodeEncoding.MainDoc">}} +[UTF32Encoding]: {{< url path = "Cortex.Reference.DataTypes.Text.UTF32Encoding.MainDoc">}} +[UTF8Encoding]: {{< url path = "MSDocs.DotNet.Api.System.Text.Utf8Encoding">}} diff --git a/content/en/docs/2024.9/Reference/data-types/wireless/_index.md b/content/en/docs/2024.9/Reference/data-types/wireless/_index.md new file mode 100644 index 000000000..cd8bf5327 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/wireless/_index.md @@ -0,0 +1,6 @@ +--- +title: "Wireless" +linkTitle: "Wireless" +description: "Data types used for working with Wireless blocks." +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceiverblockreference.md b/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceiverblockreference.md new file mode 100644 index 000000000..8395767ed --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceiverblockreference.md @@ -0,0 +1,78 @@ +--- +title: "WirelessReceiverBlockReference" +linkTitle: "WirelessReceiverBlockReference" +description: "Used to reference a Wireless Receiver block using its Id." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Wireless.WirelessReceiverBlockReference)

+ +## Summary + +A `WirelessReceiverBlockReference` is used to reference a [Wireless Receiver][Wireless Receiver Block] block that an execution can be sent to using the [Wireless Sender][Wireless Sender Block] block. + +| | | +|-|-| +| **Category:** | Wireless | +| **Name:** | `WirelessReceiverBlockReference` | +| **Full Name:** | `Cortex.DataTypes.Wireless.WirelessReceiverBlockReference` | +| **Alias:** | N/A | +| **Description:** | Used to reference a Wireless Receiver block using its Id. | +| **Default Value:** | `null` | +| **Can be used as:** | `Object`, `dynamic` | +| **Can be cast to:** | N/A | + +## Properties + +### Id + +The unique Id of the [Wireless Receiver][Wireless Receiver Block] block that is referenced. + +| | | +|--------------------|---------------------------| +| Data Type | [Guid][] | +| Is Advanced | `false` | +| Default Editor | [Literal][] | +| Default Value | No value (defaults to `00000000-0000-0000-0000-000000000000`) | + +## Remarks + +### Create a WirelessReceiverBlockReference + +Currently a `WirelessReceiverBlockReference` can only created by using the [Wireless Receiver Block Property][] of the [Wireless Sender][Wireless Sender Block] block. Using the editor to select a block will create a [Wireless Receiver Block Reference][WirelessReceiverBlockReference] for the block to use. + +### Property Editor Support + +- The Expression Editor is not available for [Input][], [InputOutput][] and [Output][] properties where the data type is `WirelessReceiverBlockReference`. +- The Literal Editor is available for [Input][] properties where the data type is `WirelessReceiverBlockReference`. +- The Variable Editor is available for [Output][] properties where the data type is `WirelessReceiverBlockReference`. + +### Known limitations + +None + +## See Also + +### Related Data Types + +- [Guid][] + +### Related Concepts + +None + +### External Documentation + +None + +[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" >}} +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} + +[WirelessReceiverBlockReference]: {{< url path="Cortex.Reference.DataTypes.Wireless.WirelessReceiverBlockReference.MainDoc" >}} +[Guid]: {{< url path="Cortex.Reference.DataTypes.Other.Guid.MainDoc" >}} +[Wireless Sender Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.MainDoc" >}} +[Wireless Receiver Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessReceiver.WirelessReceiver.MainDoc" >}} +[Wireless Receiver Block Property]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessSender.WirelessSender.WirelessReceiverProperty" >}} diff --git a/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceivernotfounderrorcode.md b/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceivernotfounderrorcode.md new file mode 100644 index 000000000..7e34b4d67 --- /dev/null +++ b/content/en/docs/2024.9/Reference/data-types/wireless/wirelessreceivernotfounderrorcode.md @@ -0,0 +1,146 @@ +--- +title: "WirelessReceiverNotFoundErrorCode" +linkTitle: "WirelessReceiverNotFoundErrorCode" +description: "Used to represent an error code explaining the reason a `WirelessReceiverBlockNotFoundException` occurred." +weight: 1 +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Wireless.WirelessReceiverNotFoundErrorCode)

+ +## Summary + +The `WirelessReceiverNotFoundErrorCode` data type is used to represent an error code explaining the reason a [WirelessReceiverBlockNotFoundException][] occurred. For more information on the exception itself, see [WirelessReceiverBlockNotFoundException][]. + +`WirelessReceiverNotFoundErrorCode` is an [enum][Working with Enums] data type, which means it has a defined set of values, where each value has an associated [String][] name and [Int32][] value. + +| | | +|-|-| +| **Category:** | Wireless | +| **Name:** | `WirelessReceiverNotFoundErrorCode` | +| **Full Name:** | `Cortex.DataTypes.Wireless.WirelessReceiverNotFoundErrorCode` | +| **Alias:** | N/A | +| **Description:** | Error code explaining the reason a [WirelessReceiverBlockNotFoundException][] occurred. | +| **Default Value:** | `(WirelessReceiverNotFoundErrorCode)0` | +| **Can be used as:** | `WirelessReceiverNotFoundErrorCode`, `Object`, `dynamic` | +| **Can be cast to:** | `Int16` (e.g. `(Int16)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(System.Int16)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(short)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`) | +| | `Int32` (e.g. `(Int32)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(System.Int32)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(int)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`) | +| | `Int64` (e.g. `(Int64)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(System.Int64)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(long)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`) | +| | `Single` (e.g. `(Single)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(System.Single)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(float)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`) | +| | `Double` (e.g. `(Double)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(System.Double)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` or `(double)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`) | + +## Values + +### WirelessReceiverBlockNotFound + +| | | +|-|-| +| **Name:** | WirelessReceiverBlockNotFound | +| **Value:** | [Int32][] with value `100` | +| **Notes:** | Used when a [WirelessReceiverBlockNotFoundException][] occurred due to the selected [Wireless Receiver][Wireless Receiver Block] block being deleted or not existing. See [Wireless Receiver Block Not Found][WirelessReceiverExceptionBlockNotFound]. | + +### WirelessReceiverPropertyEmpty + +| | | +|-|-| +| **Name:** | WirelessReceiverPropertyEmpty | +| **Value:** | [Int32][] with value `101` | +| **Notes:** | Used when a [WirelessReceiverBlockNotFoundException][] occurred due to a [Wireless Receiver][Wireless Receiver Block] block not being selected. See [Wireless Receiver Property Empty][WirelessReceiverExceptionPropertyEmpty]. | + +## Remarks + +### Create a WirelessReceiverNotFoundErrorCode + +The following table shows some of the ways that `WirelessReceiverNotFoundErrorCode` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `WirelessReceiverNotFoundErrorCode` expression | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`| Expression | Indicates a [WirelessReceiverBlockNotFoundException][] occurred due to the selected [Wireless Receiver][Wireless Receiver Block] block being deleted or not existing. | +| | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty`| Expression | Indicates a [WirelessReceiverBlockNotFoundException][] occurred due to a [Wireless Receiver][Wireless Receiver Block] block not being selected. | +| Use [Explicit Casting][] | `(WirelessReceiverNotFoundErrorCode)100` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`| Expression | Indicates a [WirelessReceiverBlockNotFoundException][] occurred due to the selected [Wireless Receiver][Wireless Receiver Block] block being deleted or not existing. | +| | `(WirelessReceiverNotFoundErrorCode)101` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty`| Expression | Indicates a [WirelessReceiverBlockNotFoundException][] occurred due to a [Wireless Receiver][Wireless Receiver Block] block not being selected. | +| Use `Enum.Parse` | `(WirelessReceiverNotFoundErrorCode)Enum.Parse(typeof(WirelessReceiverNotFoundErrorCode), "WirelessReceiverBlockNotFound")` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`| Expression | Parses `"WirelessReceiverBlockNotFound"` and converts it to `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`. See [Enum.Parse][] | +| | `(WirelessReceiverNotFoundErrorCode)Enum.Parse(typeof(WirelessReceiverNotFoundErrorCode), "WirelessReceiverPropertyEmpty")` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty`| Expression | Parses `"WirelessReceiverPropertyEmpty"` and converts it to `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty`. See [Enum.Parse][] | +| Use `Enum.ToObject` | `(WirelessReceiverNotFoundErrorCode)Enum.ToObject(typeof(WirelessReceiverNotFoundErrorCode), 100)` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound`| Expression | Converts `100` to `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` value. See [Enum.ToObject][] | +| | `(WirelessReceiverNotFoundErrorCode)Enum.ToObject(typeof(WirelessReceiverNotFoundErrorCode), 101)` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty`| Expression | Converts `101` to `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` value. See [Enum.ToObject][] | + +Please see [Instantiating an enumeration type][] for further information. + +### Convert WirelessReceiverNotFoundErrorCode to Text + +The following table shows some of the ways that a `WirelessReceiverNotFoundErrorCode` can be converted to text. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `ToString` | `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound.ToString()` | `"WirelessReceiverBlockNotFound"` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `"WirelessReceiverBlockNotFound"`. See [Enum.ToString][] | +| | `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty.ToString()` | `"WirelessReceiverPropertyEmpty"` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `"WirelessReceiverPropertyEmpty"`. See [Enum.ToString][] | +| Use `Convert.ToString` | `Convert.ToString(WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound)` | `"WirelessReceiverBlockNotFound"` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `"WirelessReceiverBlockNotFound"`. See [Convert.ToString][] | +| | `Convert.ToString(WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty)` | `"WirelessReceiverPropertyEmpty"` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `"WirelessReceiverPropertyEmpty"`. See [Convert.ToString][] | +| Use `Convert Object To Text` block | where `Object` property has a value of `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` | `"WirelessReceiverBlockNotFound"` | N/A | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `"WirelessReceiverBlockNotFound"`. See [Convert Object To Text][] | +| | where `Object` property has a value of `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` | `"WirelessReceiverPropertyEmpty"` | N/A | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `"WirelessReceiverPropertyEmpty"`. See [Convert Object To Text][] | +| Use `Convert Object To Json` block | where `Object` property has a value of `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` | `"100"` | N/A | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `"100"`. See [Convert Object To Json][] | +| | where `Object` property has a value of `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` | `"101"` | N/A | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `"101"`. See [Convert Object To Json][] | + +Please see [Formatting enumeration values][] for further information. + +### Convert WirelessReceiverNotFoundErrorCode to a Number + +The following table shows some of the ways that a `WirelessReceiverNotFoundErrorCode` can be converted to a number. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use [Explicit Casting][] | `(Int32)WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` | `100` | Expression | [Casts][Explicit Casting] `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `100` | +| | `(Int32)WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` | `101` | Expression | [Casts][Explicit Casting] `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `101` | +| Use `Convert.ToInt32` | `Convert.ToInt32(WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound)` | `100` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverBlockNotFound` to `100`. See [Convert.ToInt32][] | +| | `Convert.ToInt32(WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty)` | `101` | Expression | Converts `WirelessReceiverNotFoundErrorCode.WirelessReceiverPropertyEmpty` to `101`. See [Convert.ToInt32][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `WirelessReceiverNotFoundErrorCode`. +- The Literal Editor is available for [Input][] properties where the data type is `WirelessReceiverNotFoundErrorCode`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `WirelessReceiverNotFoundErrorCode`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +- [WirelessReceiverBlockNotFoundException][] +- [Int32][] +- [String][] + +### Related Concepts + +- [Explicit Casting][] +- [Working with Enums][] + +### External Documentation + +- [System.Enum][] + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Instantiating an enumeration type]: {{< url path="MSDocs.DotNet.Api.System.Enum.InstantiatingAnEnum" >}} +[Convert Object To Text]: {{< url path="Cortex.Reference.Blocks.Objects.ConvertObject.ConvertObjectToText.MainDoc" >}} +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} +[Working with Enums]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Enums.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[System.Enum]: {{< url path="MSDocs.DotNet.Api.System.Enum.MainDoc" >}} +[Explicit Casting]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Objects.ObjectCasting.ExplicitCast" >}} +[Formatting enumeration values]: {{< url path="MSDocs.DotNet.Api.System.Enum.FormattingEnumerationValues" >}} +[Enum.Parse]: {{< url path="MSDocs.DotNet.Api.System.Enum.Parse" >}} +[Enum.ToObject]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToObject" >}} +[Enum.ToString]: {{< url path="MSDocs.DotNet.Api.System.Enum.ToString" >}} +[Convert.ToInt32]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToInt32" >}} +[Convert.ToString]: {{< url path="MSDocs.DotNet.Api.System.Convert.ToString" >}} + +[WirelessReceiverExceptionBlockNotFound]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.BlockNotFound" >}} +[WirelessReceiverExceptionPropertyEmpty]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.PropertyEmpty" >}} +[WirelessReceiverBlockNotFoundException]: {{< url path="Cortex.Reference.Exceptions.Wireless.WirelessReceiverBlockNotFoundException.MainDoc" >}} +[Wireless Receiver Block]: {{< url path="Cortex.Reference.Blocks.Wireless.WirelessReceiver.WirelessReceiver.MainDoc" >}} diff --git a/content/en/docs/2024.9/Reference/logs/_index.md b/content/en/docs/2024.9/Reference/logs/_index.md new file mode 100644 index 000000000..a39e0d907 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/_index.md @@ -0,0 +1,6 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: "This section includes all reference documentation for the logs generated by the {{% ctx %}} Innovation platform." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/logs/cortex-gateway/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-gateway/_index.md new file mode 100644 index 000000000..f2270c8b3 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-gateway/_index.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Gateway" +linkTitle: "CORTEX Gateway" +description: "This section includes all reference documentation for the logs generated by {{% ctx %}} Gateway." +weight: 1 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/_index.md new file mode 100644 index 000000000..afecd0b81 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/_index.md @@ -0,0 +1,6 @@ +--- +title: "CORTEX Innovation" +linkTitle: "CORTEX Innovation" +description: "This section includes all reference documentation for the logs generated by the {{% ctx %}} Innovation platform." +weight: 300 +--- diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/_index.md new file mode 100644 index 000000000..3c9e946ff --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Core Application" +linkTitle: "Core Application" +description: "This section includes all reference documentation for the logs generated by the Core Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/_index.md new file mode 100644 index 000000000..409672d12 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "This section includes all reference documentation for the logs generated by the Core Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/api-gateway-service/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/api-gateway-service/_index.md new file mode 100644 index 000000000..e879f79c5 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/api-gateway-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "API Gateway Service" +linkTitle: "API Gateway Service" +description: "This section includes all reference documentation for the logs generated by the API Gateway Service." +weight: 300 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/cortex-provisioning-service/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/cortex-provisioning-service/_index.md new file mode 100644 index 000000000..300a2cc4f --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/cortex-provisioning-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Provisioning Service" +linkTitle: "Provisioning Service" +description: "This section includes all reference documentation for the logs generated by the Provisioning Service." +weight: 400 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/licence-management-service/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/licence-management-service/_index.md new file mode 100644 index 000000000..49ba579b4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/licence-management-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Licence Management Service" +linkTitle: "Licence Management Service" +description: "This section includes all reference documentation for the logs generated by the Licence Management Service." +weight: 400 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/package-management-service/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/package-management-service/_index.md new file mode 100644 index 000000000..5ea73b685 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/core-application/services/package-management-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Package Management Service" +linkTitle: "Package Management Service" +description: "This section includes all reference documentation for the logs generated by the Package Management Service." +weight: 400 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/_index.md new file mode 100644 index 000000000..af0b450d7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/_index.md @@ -0,0 +1,6 @@ +--- +title: "Execution Application" +linkTitle: "Execution Application" +description: "This section includes all reference documentation for the logs generated by the Execution Application." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/_index.md new file mode 100644 index 000000000..af20654a1 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/_index.md @@ -0,0 +1,6 @@ +--- +title: "Services" +linkTitle: "Services" +description: "This section includes all reference documentation for the logs generated by the Execution Application Services." +weight: 1 +--- diff --git a/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/execution-service/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/execution-service/_index.md new file mode 100644 index 000000000..554e7fe79 --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-innovation/execution-application/services/execution-service/_index.md @@ -0,0 +1,8 @@ +--- +title: "Execution Service" +linkTitle: "Execution Service" +description: "This section includes all reference documentation for the logs generated by the Execution Service." +weight: 400 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/logs/cortex-studio/_index.md b/content/en/docs/2024.9/Reference/logs/cortex-studio/_index.md new file mode 100644 index 000000000..6ed9f36ef --- /dev/null +++ b/content/en/docs/2024.9/Reference/logs/cortex-studio/_index.md @@ -0,0 +1,8 @@ +--- +title: "CORTEX Studio" +linkTitle: "CORTEX Studio" +description: "This section includes all reference documentation for the logs generated by {{% ctx %}} Studio." +weight: 100 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/messages/_index.md b/content/en/docs/2024.9/Reference/messages/_index.md new file mode 100644 index 000000000..ae112e0d4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/messages/_index.md @@ -0,0 +1,8 @@ +--- +title: "Messages" +linkTitle: "Messages" +description: "This section includes all reference documentation for messages generated by the {{% ctx %}} Innovation platform." +weight: 10 +--- + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/messages/validation/_index.md b/content/en/docs/2024.9/Reference/messages/validation/_index.md new file mode 100644 index 000000000..92c14ec15 --- /dev/null +++ b/content/en/docs/2024.9/Reference/messages/validation/_index.md @@ -0,0 +1,8 @@ +--- +title: "Validation" +linkTitle: "Validation" +description: "This section includes all reference documentation for messages generated during validation." +weight: 100 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/messages/validation/errors/_index.md b/content/en/docs/2024.9/Reference/messages/validation/errors/_index.md new file mode 100644 index 000000000..358ee1e21 --- /dev/null +++ b/content/en/docs/2024.9/Reference/messages/validation/errors/_index.md @@ -0,0 +1,8 @@ +--- +title: "Errors" +linkTitle: "Errors" +description: "This section includes all reference documentation for errors generated during validation." +weight: 1 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Reference/observability/_index.md b/content/en/docs/2024.9/Reference/observability/_index.md new file mode 100644 index 000000000..804cf9d57 --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/_index.md @@ -0,0 +1,6 @@ +--- +title: "Observability" +linkTitle: "Observability" +description: "This section includes all reference documentation for the Observability platform for {{% ctx %}} Innovation." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/observability/grafana/_index.md b/content/en/docs/2024.9/Reference/observability/grafana/_index.md new file mode 100644 index 000000000..a4fd22ff7 --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/_index.md @@ -0,0 +1,6 @@ +--- +title: "Grafana" +linkTitle: "Grafana" +description: "This section includes all reference documentation for the Grafana Observability platform for {{% ctx %}} Innovation." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/_index.md b/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/_index.md new file mode 100644 index 000000000..0b45d5ce2 --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/_index.md @@ -0,0 +1,6 @@ +--- +title: "Advanced Setup" +linkTitle: "Advanced Setup" +description: "This section includes supporting documentation for the Grafana Observability platform." +weight: 20 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/configuring-thresholds.md b/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/configuring-thresholds.md new file mode 100644 index 000000000..57c7d2e87 --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/advanced-setup/configuring-thresholds.md @@ -0,0 +1,32 @@ +--- +title: "Configuring Thresholds" +linkTitle: "Configuring Thresholds" +description: "Instructions on how to configure thresholds in the Grafana Dashboard panels." +weight: 30 +--- + +# {{% param title %}} + +## Configure Thresholds + +This section explains how to change the colour coding of thresholds set for the thresholded panels in the dashboards. + +1. Log in to your configured Grafana with a user that has the *Admin* role. +1. To open a dashboard: + 1. Open the *Dashboards* page via the menu on the left sidebar. + 1. Click the folder name that the dashboards were imported to. + 1. Click the name of the dashboard you wish to modify to open it. +1. Open the panel you wish to configure in edit mode: + 1. Click the title of the panel to display a drop-down menu. + 1. Click *Edit*. +1. On the *Edit Panel* page, on the right-hand side, scroll down through the list of options until you reach the *Thresholds* section. + 1. You can change the value configured for the colours defined if the thresholds should be different to the default set for that panel. + 1. You can change the colours defined for the thresholds to be different to the default set for that panel. + 1. You can add additional threshold levels by clicking *+ add threshold* and configuring the colours and numbers appropriately. E.g. on the [Total Requests Errored][] panel on the [Flow Execution Requests][] dashboard, you may wish to add a warning threshold level to be >= 1 errors and change the critical threshold to be >= 10. For this you should add a threshold and set the colour to your preferred colour, set the value to 1 and change the value for red to be 10. + 1. The threshold should be set to be an absolute value if it is a count e.g. error count, or a percentage if it is a rate e.g. success rate. +1. Click *Apply* in the top right corner of the Edit Panel page. +1. Save the changes to the dashboard by clicking on the save (disk) icon, in the top right of the dashboard. + + +[Flow Execution Requests]: {{< url path="Cortex.Reference.Observability.Grafana.Dashboards.FlowExecutionRequests.MainDoc" >}} +[Total Requests Errored]: {{< url path="Cortex.Reference.Observability.Grafana.Dashboards.FlowExecutionRequests.TotalRequestsErrored" >}} diff --git a/content/en/docs/2024.9/Reference/observability/grafana/dashboards/_index.md b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/_index.md new file mode 100644 index 000000000..f228671eb --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/_index.md @@ -0,0 +1,6 @@ +--- +title: "Dashboards" +linkTitle: "Dashboards" +description: "This section includes all reference documentation for the {{% ctx %}} Innovation default set of Grafana dashboards." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/observability/grafana/dashboards/flow-execution-requests.md b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/flow-execution-requests.md new file mode 100644 index 000000000..a2811746b --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/flow-execution-requests.md @@ -0,0 +1,216 @@ +--- +title: "Flow Execution Requests" +linkTitle: "Flow Execution Requests" +description: "Information about the Flow Executions Request Dashboard." +weight: 10 +--- + +# {{% param title %}} + +## Description + +This dashboard provides the information required to analyse the flow execution requests within the {{% ctx %}} Innovation platform. It will display data based on the [Time Range][] that has been specified. + +At the top of the page there is a dashboard description. This provides information about what the dashboard is reporting and what each of the filters are. The description is always collapsed by default. + +The dashboard is then split into 4 main sections: + +- [Overview](#overview-section) +- [Requests](#requests-section) +- [Errors](#errors-section) +- [Duration](#duration-section) + +There are several [filters](#filters) available to filter the data to a more fine-grained level as necessary and are explained in further detail below. + +{{< figure src="/images/editable/Flow Execution Requests Dashboard.png" >}} + +## Time Range + +{{% alert type="note" title="Note" %}}Choosing large time ranges will increase the time it takes for the data to be loaded into the dashboard.{{% /alert %}} + +The time range for which the dashboard displays data is configurable in the top right of the dashboard using the Time Range selector (defaults to the last 3 hours): + +{{< figure src="/images/editable/Flow Execution Requests - Time Range.png">}} + +There are a number of predefined quick ranges to choose from: + +- Last 5, 15 and 30 minutes +- Last 1, 3, 6, 12 and 24 hours +- Last 2, 7, 30 and 90 days +- Last 6 months +- Last 1, 2 and 5 years +- Yesterday +- Day before yesterday +- This day last week +- Previous week, month, fiscal quarter, year, fiscal year +- Today +- Today so far +- This month, fiscal quarter, year and fiscal year +- This month, fiscal quarter, year and fiscal year so far + +To configure an absolute time range, you should specify a From and To date and time. These values can be in the format of `YYYY-MM-DD HH:MM:SS`, e.g. `2022-07-22 13:54:23`, or alternatively can use times relative to now, e.g. `now-24h`. It is also possible to use the date time picker available for both the From and To fields. Once the absolute time range has been configured you must click the 'Apply time range' button. + +If an absolute time range is specified, the Time Range selector will show the selected time range with arrows either side. These arrows can be used to shift the time range forwards and backwards. This feature is not available for quick ranges. + +{{< figure src="/images/editable/Flow Execution Requests - Time Range extended.png">}} + +The magnifying glass icon allows you to zoom out of the time range specified. It will substract half the current time range from the From field and add half the current time range to the To field. + +For more information regarding the Time Range selector, see Grafana's [Time range controls][] documentation. + +## Filters + +At the top of the dashboard, there are 10 filters available to restrict the data queried: + +{{< figure src="/images/editable/Flow Execution Requests - Filters.png" >}} + +|Filter |Description| +|--------|-----------| +| Tenant | List of tenants. Defaulted to All. | +| System | List of systems. Defaulted to All. | +| Node | List of hosts that processed the requests. Defaulted to All. | +| Package Name | List of packages. Defaulted to All. | +| Flow Name | List of flows that have execution requests. Defaulted to All. | +| Status Code | List of [status codes][] found in the HTTP responses. Defaulted to All. | +| Result | List of results found in the HTTP responses. Defaulted to All. | +| Initiator IP Address | List of IP addresses for the initiators of the requests. Defaulted to All. | +| Interval | List of intervals to perform the time series aggregations upon. This only affects the graphs on this dashboard.

The available values for this filter are auto, 1m, 10m, 30m, 1h, 6h, 12h, 1d, 7d, 14d, 30d.

If *auto* is selected, as is the default, Grafana will aggregate to a level it deems appropriate for the time range specified. | +| Custom Filter | Enables filtering on all available values, including those not exposed by default. | + +All filters (excluding Interval and Custom Filter) will display their list of available options dependent on the preceding filters selected. + +## Overview Section + +This section displays key flow execution request metrics for the specified [time range][] and consists of 4 panels. + +{{< figure src="/images/editable/Flow Execution Requests - Overview.png" >}} + +{{% alert type="note" title="Note" %}}The Interval filter does not affect these panels.{{% /alert %}} + +### Total Requests + +This tile displays the total number of flow execution requests during the specified [time range][]. + +### Total Requests Errored + +This tile displays the total number of flow execution requests that errored during the specified [time range][]. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be [customised][customise threholds], however the default thresholds are: + +| Threshold | Value | Colour | +|------------------|-----------|------------| +| OK | 0 | green | +| CRITICAL | >= 1 | red | + +### Request Error Rate + +This tile displays the percentage of errored flow execution requests against the total flow execution requests during the specified [time range][]. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be [customised][customise threholds], however the default thresholds are: + +| Threshold | Value | Colour | +|------------------|-----------|------------| +| OK | < 5% | green | +| WARNING | >= 5% | orange | +| CRITICAL | >= 10% | red | + +### Mean Request Duration + +This tile displays the mean duration for flow execution requests during the specified [time range][]. This is usually reported in seconds, however the unit may change if the number is much smaller or larger. + +## Requests Section + +This section provides information regarding the flow execution request history for the specified [time range][] and consists of 3 panels. + +{{< figure src="/images/editable/Flow Execution Requests - Requests.png" >}} + +### Requests + +This graph displays, for the specified [time range][], the: + +- count of all flow execution requests +- mean duration in seconds for all flow execution requests + +Each data point value is calculated by aggregating requests based on the Interval filter. + +### Top 10 Requests by Count + +This table displays the 10 flows with the most execution requests during the specified [time range][] with their mean, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +### Bottom 10 Requests by Count + +This table displays the 10 flows with the least execution requests during the specified [time range][] with their mean, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table. Also, any flows with zero executions will not be displayed.{{% /alert %}} + +## Errors Section + +This section provides information regarding the errored flow execution request history for the specified [time range][] and consists of 2 panels. + +{{< figure src="/images/editable/Flow Execution Requests - Errors.png" >}} + +### Errored Requests + +This graph displays, for the specified [time range][], the: + +- count of errored flow execution requests +- mean duration in seconds for errored flow execution requests + +Each data point value is calculated by aggregating requests based on the Interval filter. + +### Top 10 Requests by Error Count + +This table displays the 10 flows with the most errored execution requests (by status code and result) during the specified [time range][] with their mean, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +## Duration Section + +This section provides information regarding the flow execution request duration history for the specified [time range][] and consists of 3 panels. + +{{< figure src="/images/editable/Flow Execution Requests - Duration.png" >}} + +### Request Duration + +This graph displays, for the specified [time range][], the: + +- mean duration in seconds for all flow execution requests +- minimum duration in seconds for all flow execution requests +- maximum duration in seconds for all flow execution requests + +Each data point value is calculated by aggregating requests based on the Interval filter. + +### Top 10 Longest Running Requests by Mean Duration + +This table displays the 10 flows whose execution requests have the longest mean duration during the specified [time range][] with their total count, error count, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +### Top 10 Shortest Running Requests by Mean Duration + +This table displays the 10 flows whose execution requests have the shortest mean duration during the specified [time range][] with their total count, error count, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table. Also, any flows with zero executions will not be displayed.{{% /alert %}} + +## Remarks + +### Unknown values + +The dashboard may display flow execution requests that have an `Unknown` status code or result, if they are missing from the raw logs. The chances of this occurring are minimal. + +### Known Limitations + +#### Graphs do not reset to zero + +There is a limitation in Grafana where the graph does not always return to the zero line when there is no data for a given time point. This only occurs when there is a data point available at the beginning of the graph, followed by a period with no data, then data occurs again. When hovering the mouse over this area, it will show that the value is 0, and any other tiles will reflect the zero data at this point accordingly. + +{{< figure src="/images/editable/Flow Execution Requests - Not Zero.png" >}} + +## Related Dashboards + +None + +[time range]: #time-range + + +[customise threholds]: {{< url path="Cortex.Reference.Observability.Grafana.Dashboards.Grafana.AdvancedSetup.ConfigureThresholds.MainDoc" >}} +[status codes]: {{< url path="Wikipedia.HttpStatusCodes" >}} +[Time range controls]: {{< url path="Grafana.Products.Grafana.TimeRange" >}} diff --git a/content/en/docs/2024.9/Reference/observability/grafana/dashboards/platform-health.md b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/platform-health.md new file mode 100644 index 000000000..758b4e4b4 --- /dev/null +++ b/content/en/docs/2024.9/Reference/observability/grafana/dashboards/platform-health.md @@ -0,0 +1,237 @@ +--- +title: "Platform Health" +linkTitle: "Platform Health" +description: "Information about the Platform Health Dashboard." +weight: 20 +--- + +# {{% param title %}} + +## Description + +This dashboard provides the information required to analyse the health of the {{% ctx %}} Innovation platform. It will display data based on the [Time Range][] that has been specified. + +At the top of the page there is a dashboard description. This provides information about what the dashboard is reporting and what each of the filters are. The description is always collapsed by default. + +The dashboard is then split into 5 main sections: + +- [Overview](#overview-section) +- [Availability](#availability-section) +- [Requests](#requests-section) +- [Errors](#errors-section) +- [Duration](#duration-section) + +There are several [filters](#filters) available to filter the data to a more fine-grained level as necessary and are explained in further detail below. + +{{< figure src="/images/editable/Platform Health Dashboard.png" >}} + +## Time Range + +{{% alert type="note" title="Note" %}}Choosing large time ranges will increase the time it takes for the data to be loaded into the dashboard.{{% /alert %}} + +The time range for which the dashboard displays data is configurable in the top right of the dashboard using the Time Range selector (defaults to the last 3 hours): + +{{< figure src="/images/editable/Platform Health - Time Range.png">}} + +There are a number of predefined quick ranges to choose from: + +- Last 5, 15 and 30 minutes +- Last 1, 3, 6, 12 and 24 hours +- Last 2, 7, 30 and 90 days +- Last 6 months +- Last 1, 2 and 5 years +- Yesterday +- Day before yesterday +- This day last week +- Previous week, month, fiscal quarter, year, fiscal year +- Today +- Today so far +- This month, fiscal quarter, year and fiscal year +- This month, fiscal quarter, year and fiscal year so far + +To configure an absolute time range, you should specify a From and To date and time. These values can be in the format of `YYYY-MM-DD HH:MM:SS`, e.g. `2022-07-22 13:54:23`, or alternatively can use times relative to now, e.g. `now-24h`. It is also possible to use the date time picker available for both the From and To fields. Once the absolute time range has been configured you must click the 'Apply time range' button. + +If an absolute time range is specified, the Time Range selector will show the selected time range with arrows either side. These arrows can be used to shift the time range forwards and backwards. This feature is not available for quick ranges. + +{{< figure src="/images/editable/Platform Health - Time Range extended.png">}} + +The magnifying glass icon allows you to zoom out of the time range specified. It will substract half the current time range from the From field and add half the current time range to the To field. + +For more information regarding the Time Range selector, see Grafana's [Time range controls][] documentation. + +## Filters + +At the top of the dashboard, there are 9 filters available to restrict the data queried: + +{{< figure src="/images/editable/Platform Health - Filters.png">}} + +|Filter |Description| +|--------|-----------| +| Tenant | List of tenants. Defaulted to All. | +| System | List of systems. Defaulted to All. | +| Node | List of hosts that processed the requests. Defaulted to All. | +| API | List of the API endpoints found in the HTTP requests. Defaulted to All. | +| Status Code | List of [status codes][] found in the HTTP responses. Defaulted to All. | +| Result | List of results found in the HTTP responses. Defaulted to All. | +| Initiator IP Address | List of IP addresses for the initiators of the requests. Defaulted to All. | +| Interval | List of intervals to perform the time series aggregations upon. This only affects the graphs on this dashboard.

The available values for this filter are auto, 1m, 10m, 30m, 1h, 6h, 12h, 1d, 7d, 14d, 30d.

If *auto* is selected, as is the default, Grafana will aggregate to a level it deems appropriate for the time range specified. | +| Custom Filter | Enables filtering on all available values, including those not exposed by default. | + +All filters (excluding Interval and Custom Filter) will display their list of available options dependent on the preceding filters selected. + +## Overview Section + +This section displays key platform health metrics for the specified [time range][] and consists of 4 panels. + +{{< figure src="/images/editable/Platform Health - Overview.png">}} + +{{% alert type="note" title="Note" %}}The Interval filter does not affect these panels.{{% /alert %}} + +### Availability + +This tile displays the availability of the platform by calculating the successful requests / total requests during the specified [time range][]. Successful requests are all requests that do not result in a 5xx HTTP response, 4xx responses are considered successful in this scenario. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be [customised][customise threholds], however the default thresholds are: + +| Threshold | Value | Colour | +|------------------|-----------|------------| +| OK | >= 95% | green | +| WARNING | >= 90% | orange | +| CRITICAL | < 90% | red | + +### Total Requests + +This tile displays the total number of requests during the specified [time range][]. + +### Errored Requests + +This tile displays the total number of errored requests during the specified [time range][]. Errored requests are all requests that result in an unknown or 5xx HTTP response, 4xx responses are considered successful in this scenario. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be [customised][customise threholds], however the default thresholds are: + +| Threshold | Value | Colour | +|------------------|-----------|------------| +| OK | 0 | green | +| CRITICAL | >= 1 | red | + +### Mean Request Duration + +This tile displays the mean duration for requests during the specified [time range][]. + +{{% alert type="note" title="Note" %}}Certain APIs may take significantly longer than others skewing the result.{{% /alert %}} + +## Availability Section + +This section displays the availability of the {{% ctx %}} Innovation platform and consists of 1 panel. + +{{< figure src="/images/editable/Platform Health - Availability.png">}} + +### Availability + +This graph displays the availability of the {{% ctx %}} Innovation Platform during the specified [time range][] by calculating successful requests / total requests. Successful requests are all requests that do not result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario. + +Each data point value is calculated by aggregating requests based on the Interval filter. If there is no data for the previous interval, the line will be [broken](#breaks-in-graph-lines) as the availability is not known at the time. + +This graph has thresholds set to colour code the background to show when availability drops into warning and critical levels. These thresholds can be [customised][customise threholds], however the default thresholds are: + +| Threshold | Value | Colour | +|------------------|-----------|------------| +| OK | >= 95% | green | +| WARNING | >= 90% | orange | +| CRITICAL | < 90% | red | + +This graph is configured to start the availability axis at 80%. However, if the availability drops below this level, the axis will modify to show the lowest availability level. + +## Requests Section + +This section provides information regarding the history of the requests processed by the {{% ctx %}} Innovation platform for the specified [time range][] and consists of 2 panels. + +{{< figure src="/images/editable/Platform Health - Requests.png">}} + +### Requests + +This graph displays, for the specified [time range][], the: + +- count of all requests. Each data point value is calculated by aggregating requests based on the Interval filter. +- count of all requests per second. + +### Top 10 Responses by Total Count + +This table displays the Top 10 HTTP responses that occurred during the specified [time range][] with their mean, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +## Errors Section + +This section provides information regarding the errored request history for the specified [time range][] and consists of 2 panels. + +{{< figure src="/images/editable/Platform Health - Errors.png">}} + +### Errored Requests + +This graph displays, for the specified [time range][], the: + +- count of errored requests +- count of all requests + +Each data point value is calculated by aggregating requests based on the Interval filter. + +Errored requests are all requests that result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario. + +### Top 10 Error Responses by Error Count + +This table displays the Top 10 HTTP error responses that occured during the specified [time range][] with their mean, minimum and maximum duration in seconds. Errored requests are all requests that result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +## Duration Section + +This section provides information regarding the request duration history for the specified [time range][] and consists of 2 panels. + +{{% alert type="note" title="Note" %}}Certain APIs may take significantly longer than others skewing the result.{{% /alert %}} + +{{< figure src="/images/editable/Platform Health - Duration.png">}} + +### Request Duration + +This graph displays, for the specified [time range][], the: + +- mean duration in seconds for all requests +- minimum duration in seconds for all requests +- maximum duration in seconds for all requests + +Each data point value is calculated by aggregating requests based on the Interval filter. + +### Top 10 Responses by Mean Duration + +This table displays the top 10 HTTP responses that occurred during the specified [time range][] with their mean, minimum and maximum duration in seconds. + +{{% alert type="note" title="Note" %}}The Interval filter does not affect this table.{{% /alert %}} + +## Remarks + +### Unknown values + +The dashboard may display HTTP requests that have an `Unknown` status code or result, if they are missing from the raw logs. The chances of this occurring are minimal. + +### Breaks in Graph Lines + +When appropriate, there may occur breaks in the line graphs. This is relevant to the Availability graph. When there is no data, it is not appropriate to say that the availability is the same as the previous data point or that it is zero as if there is no data, we cannot accurately reflect the data at this point, and therefore, the line will break. + +{{< figure src="/images/editable/Platform Health - Break in Line.png">}} + +### Known Limitations + +#### Graphs do not reset to zero + +There is a limitation in Grafana where the graph does not always return to the zero line when there is no data for a given time point. This only occurs when there is a data point available at the beginning of the graph, followed by a period with no data, then data occurs again. When hovering the mouse over this area, it will show that the value is 0, and any other tiles will reflect the zero data at this point accordingly. + +{{< figure src="/images/editable/Platform Health - Not Zeros.png">}} + +## Related Dashboards + +None + + +[time range]: #time-range + + +[customise threholds]: {{< url path="Cortex.Reference.Observability.Grafana.Dashboards.Grafana.AdvancedSetup.ConfigureThresholds.MainDoc" >}} +[status codes]: {{< url path="Wikipedia.HttpStatusCodes" >}} +[Time range controls]: {{< url path="Grafana.Products.Grafana.TimeRange" >}} diff --git a/content/en/docs/2024.9/Reference/troubleshooting/_index.md b/content/en/docs/2024.9/Reference/troubleshooting/_index.md new file mode 100644 index 000000000..2a499feb8 --- /dev/null +++ b/content/en/docs/2024.9/Reference/troubleshooting/_index.md @@ -0,0 +1,6 @@ +--- +title: "Troubleshooting" +linkTitle: "Troubleshooting" +description: "This section includes information about how to troubleshoot the platform." +weight: 100 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Reference/troubleshooting/installation.md b/content/en/docs/2024.9/Reference/troubleshooting/installation.md new file mode 100644 index 000000000..642d399ef --- /dev/null +++ b/content/en/docs/2024.9/Reference/troubleshooting/installation.md @@ -0,0 +1,344 @@ +--- +title: "Installation" +linkTitle: "Installation" +description: "Information on troubleshooting {{% ctx %}} Innovation installations." +--- + +# {{% param title %}} + +## Troubleshooting issues during installation {#ts-during-installation} + +### Root certificate verification failed as no root certificate has been specified {#ts-no-root-certificate} + +If the installation fails with `Root certificate verification failed as no root certificate has been specified.` it means that Windows has not got the trusted root installed for the provided X.509 certificate. This can be rectified by providing the path to a .pem file containing the root certificate in the `pemRootCertificatePath` property for each certificate in the `serverCertificates` and/or `adminCertificates` section of the configuration file. After adding this, the installation script can be re-run. The following steps can be taken to create a .pem file and re-run the installation (these instructions may differ slightly depending on the Certificate Authority): + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + +1. In order to find out the issuer of the certificate, if not already known, the following script can be used, replacing the password for the pfx file and certificate path as necessary: + + ```powershell + $p = ConvertTo-SecureString -String "pfxPassword" -AsPlainText -Force + $c = Get-PfxData -Password $p -FilePath "C:\Certificates\serverCert.pfx" + $c | Format-List + ``` + +1. This will give a list of `Other Certificates` and `End Certificates` contained in the .pfx file. The issuer can be found in the `Issuer` property of one of the `Other Certificates`. If there are more than one, it will be the one that does not appear as a `Subject` in any of the other items. +1. E.g. For a "Let's Encrypt" certificate this will give the following results: + + ```powershell + OtherCertificates : {[Subject] + CN=Let's Encrypt Authority X3, O=Let's Encrypt, C=US + [Issuer] + CN=DST Root CA X3, O=Digital Signature Trust Co. + [Serial Number] + 0A0141420000015385736A0B85ECA708 + [Not Before] + 17/03/2016 16:40:46 + [Not After] + 17/03/2021 16:40:46 + [Thumbprint] + E6A3B45B062D509B3382282D196EFE97D5956CCB + } + EndEntityCertificates : {[Subject] + CN=*.domain.com + [Issuer] + CN=Let's Encrypt Authority X3, O=Let's Encrypt, C=US + [Serial Number] + 03D3B2E5E7D75175C25B250305650ABE849A + [Not Before] + 20/12/2019 16:27:36 + [Not After] + 19/03/2020 16:27:36 + [Thumbprint] + D61356405B8D4AA11C29AF3D20F2D834C1A3039F + } + ``` + +1. In this case, the root certificate is `DST Root CA X3`. +1. In a search engine, search for the CN of the issuer and one of the results should lead to a download of a .pem file or to a page with the certificate on it, which can then be copied and saved into a file with a .pem extension. Often, searching the issuer of the EndEntityCertificate, in the above case `Let’s Encrypt`, will also work. +1. E.g. for `Let’s Encrypt`, the results of the search for `DST Root CA X3` leads to `https://www.identrust.com/dst-root-ca-x3` which provides the following text to be saved as a .pem file: + + ```markdown + -----BEGIN CERTIFICATE----- + MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/ + MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT + DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow + PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD + Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB + AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O + rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq + OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b + xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw + 7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD + aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV + HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG + SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69 + ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr + AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz + R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5 + JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo + Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ + -----END CERTIFICATE----- + ``` + +1. After saving the .pem file, transfer it to the same directory as other installation certificates. +1. Modify the installation configuration file to include the .pem file as the `pemRootCertificatePath` in the `serverCertificates` like so: + + ```json + "serverCertificates": { +     "serverCert": { +       "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx", +       "pfxCertificatePassword": "#_121004188127116!133150189159197057145221234081254~237141201182240!228132117152122101166250091035249#", +       "pemRootCertificatePath": "C:\\Certificates\\rootCert.pem" +     } +   } + ``` + + {{< alert type="note" title="Note" >}} The `pfxCertificatePassword` parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} + +1. If a load balancer is being used (not single server), modify the installation configuration file to include the .pem file as the `pemRootCertificatePath` in the `adminCertificates` like so: + + ```json + "adminCertificates": { +     "loadBalancerCert": { +       "pfxCertificatePath": "C:\\Certificates\\lbCert.pfx", +       "pfxCertificatePassword": "#_121004188127116!133150189159197057145221234081254~237141201182240!228132117152122101166250091035249#", +       "pemRootCertificatePath": "C:\\Certificates\\lbRootCert.pem" +     } +   } + ``` + + {{< alert type="note" title="Note" >}} The `pfxCertificatePassword` parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} + +1. Run the installation script again. + +### RabbitMQ commands not succeeding + +When running the installation, if you get errors similar to the following: + +``` shell +Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames . Attempt 1 +Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames . Attempt 2 +Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames . Attempt ... +Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames . Attempt 20 +``` + +It means there is probably something wrong with the certificate verification with RabbitMQ. Please report issues like this to [{{% ctx %}} Service Portal][CORTEX Service Portal]. + +To work around this error, either uninstall the platform and reinstall it using a different certificate, otherwise disable peer-to-peer verification in RabbitMQ by carrying out the following steps: + +1. Uninstall the platform by taking the following steps: + 1. Open a Windows PowerShell (x64) window as administrator. + 1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + + 1. Uninstall the platform by running the following command for your architecture: + + {{< tabpane lang="powershell" >}} + {{< tab header="Multiple Servers With HA" >}} + .\Cortex.Innovation.Uninstall.ps1 + {{< /tab >}} + {{< tab header="Single Server Without HA" >}} + .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer + {{< /tab >}} + {{< /tabpane >}} + 1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. + 1. Wait for the command to finish. +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, navigate to `Resources`. +1. Backup the file `RabbitMqInterNodePublicTemplate.config` and then open it with a text editor. +1. Replace both instances of the text `verify_peer` with the text `verify_none`. +1. Change the value of both occurrences of `fail_if_no_peer_cert` to `false` so that they resemble the following: + + ```shell + {fail_if_no_peer_cert, false}, + ``` + +1. Save and close `RabbitMqInterNodePublicTemplate.config`. +1. Re-run the installation script. + +## Troubleshooting issues after installation {#ts-after-installation} + +### {{% ctx %}} Innovation features not visible in {{% ctx %}} Gateway {#ts-no-innovation} + +Check that the `Feature Flags` Guid in the `CortexGateway.SetParameters.xml` file used for installing {{% ctx %}} Gateway is correct. If it is not, update it and reinstall {{% ctx %}} Gateway or update the value in the `web.config` file and restart the website. If the value is correct, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +### {{% ctx %}} Innovation blocks not visible in {{% ctx %}} Studio {#ts-no-blocks} + +#### Application Pool user does not have Modify rights to the Roaming folder + +The following folders require `Modify` permission to allow creating the `NuGet` folders and its `NuGet.Config` file within: + +* `C:\Windows\System32\config\systemprofile\AppData\Roaming` +* `C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming` + +For each folder, perform the following steps: + +1. Navigate to the `AppData` folder. +1. Right-click on the `Roaming` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. + +#### Application Pool user does not have rights to the Cortex Blocks Provider Host folder + +Perform the following steps: + +1. Navigate to `C:\ProgramData\Cortex` +1. Right-click on the `Cortex Blocks Provider Host` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + +#### Perform an IIS reset + +1. Open a Windows PowerShell (x64) window as administrator. +1. Run the following command: `iisreset`. +1. Wait for the action to complete. + +### Flow not starting in {{% ctx %}} Gateway {#ts-flow-not-starting} + +#### Application Pool user does not have rights to the Repo folder + +Check that the `Application Pool` user has rights to the `Repo` folder using the following steps: + +1. Check where the `Repo` folder is located + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. Navigate to the `Repo` folder, not opening it. +1. Right-click on the `Repo` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + +### Cannot publish a package {#ts-no-publish} + +Check that the `Service Fabric Api Gateway Endpoint`, `Service Fabric Using Self Signed Certificates`, `Service Fabric ApiGateway Basic Auth Username` and `Service Fabric ApiGateway Basic Auth Password` in the `CortexGateway.SetParameters.xml` file used for installing {{% ctx %}} Gateway are correct. If any of them are not, update them and reinstall {{% ctx %}} Gateway or update the value in the "web.config" file and restart the website. If the value is correct, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +Ensure that the Application Services are healthy by following these steps: + +1. Log on to one of the Application Servers and open a web browser. +1. Navigate to `https://app-server.domain.com:9080/Explorer`, where `app-server.domain.com` is the fully qualified domain name of any Application Server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration. + + If page access is denied it may be necessary to import the server certificate used in installation to the Current User certificate store (usually achieved by double clicking on it and following the wizard). If using self-signed certificates, the certificate can be retrieved by using the `Manage Computer Certificates` tool in Windows to export the `CortexServerCertificate` from the `Personal` store as a pfx file and then importing it to the `Current User` store by double-clicking on it and following the wizard. The certificate must also be imported to `Trusted Root Certification Authorities` in the `Local Computer` store. The browser may need to be restarted before the site can be accessed. + + The screen should resemble that in the following figure, all services should have `Health State = OK` and `Status = Active`. All instances below the service should have Health State = OK and Status = Ready. + + {{< figure src="/images/Service Fabric Explorer.png" title="Healthy Service Fabric Explorer" >}} + + If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, ignore the rest of this step. If the warnings persist or anything on the screen goes red, use the filter buttons to find the individual elements which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. + If no useful message can be seen here, the service log files may contain more information. + +If no solution can be found, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +### Managing RabbitMQ + +There may be times when the logs provided by {{% ctx %}} Innovation Services and the errors displayed in Service Fabric Explorer are not enough to debug an issue that is occurring on the system. This can be due to RabbitMQ being a state where it can’t send messages between services. + +To check that RabbitMQ is working as expected, remote desktop to an Application Server and navigate to `https://app-server1.domain.com:15671`, replacing `app-server1.domain.com` with the FQDN of one of the Application Servers. Sign in with username 'administrator' and the RabbitMQ password provided during the Application Server installation. The following should be displayed in the overview tab for a healthy cluster: + +{{< figure src="/images/RabbitMQ Status.png" title="Healthy RabbitMQ status." >}} + +{{% alert title="Note" %}} The username and password are not secure, but the RabbitMQ manager will only allow you to connect from localhost so it is not accessible to anyone who does not have remote desktop access. {{% /alert %}} + +If there are any unhealthy nodes (red) you may need to restart the RabbitMQ Windows service on each of the nodes that is erroring. These can be restarted in any order, but they must be restarted one at a time; wait for the node in the RabbitMQ explorer to be green before restarting the next one (you may need to refresh the browser). + +### Service Fabric Explorer displays errored services with RabbitMQ Broker Unreachable Exceptions + +If, when checking Service Fabric Explorer, all services are showing as erroring and the details are displaying a message similar to the following: + +```text +RabbitMQ.Client.Exceptions.BrokerUnreachableException (-2146232800) +None of the specified endpoints were reachable +``` + +There may be due to an incompatibility between the version of OpenSSL used and your processor. From Intel's website: **"OpenSSL* 1.0.2 beta (Jun 2014) to OpenSSL 1.0.2k (Jan 2017) contain bugs that either cause a crash or bad SHA (Secure Hash Algorithm) values on processors with the SHA extensions. Both bugs were fixed years ago; however, any application that uses the old version directly, or as one of its dependencies, will fail"** + +To verify that this is the problem, open Event Viewer and look in Windows -> Application. If this problem has occurred there will be some errors in the event viewer which contain the following: + +```text +Faulting application name: erl.exe, version: 0.0.0.0, time stamp: 0x5d80b978 +Faulting module name: crypto.dll, version: 0.0.0.0, time stamp: 0x5d80baab +``` + +A workaround for this is provided by Intel. + +1. Uninstall the platform by taking the following steps: + 1. Open a Windows PowerShell (x64) window as administrator. + 1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + + 1. Uninstall the platform by running the following command for your architecture: + + {{< tabpane lang="powershell" >}} + {{< tab header="Multiple Servers With HA" >}} + .\Cortex.Innovation.Uninstall.ps1 + {{< /tab >}} + {{< tab header="Single Server Without HA" >}} + .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer + {{< /tab >}} + {{< /tabpane >}} + 1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. + 1. Wait for the command to finish. +1. Add a system environment variable, provided by Intel, to each Application Server by taking the following steps: + 1. Remote desktop to one of the Application Servers. + 1. Right-click on the Start Menu and select `System`. + 1. Click `Advanced system settings` to open the System Properties dialog. + 1. Click `Environment Variables...`. + 1. Under `System variables`, click `New...` to open the New System Variable dialog. + 1. Set the Variable name to `OPENSSL_ia32cap` and the Variable value to `:~0x20000000`. Make sure to include the colon at the start. + 1. Click OK. + 1. Repeat these steps for any other Application Servers. +1. Run the Application Servers installation script again. + +### Service Fabric Explorer displays certificate is about to expire warning + +If Service Fabric certificates are going to expire in fewer than 30 days, a warning is displayed as follows: + +{{< figure src="/images/Service Fabric Explorer - Expiring Certificate.PNG" title="Service Fabric Explorer Certificate Expiring" >}} + +*Certificate expiration: thumbprint = {thumbprint}, expiration {date} remaining lifetime is {time} please refresh ahead of time to avoid catastrophic failure.* + +If this occurs on your server it is important to update your certificates as soon as possible using [Rollover Certificates][]. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Rollover Certificates]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" >}} +[add rights to nuget folder]: {{< ref "#ts-add-rights-to-nuget-folder" >}} diff --git a/content/en/docs/2024.9/Reference/troubleshooting/upgrade.md b/content/en/docs/2024.9/Reference/troubleshooting/upgrade.md new file mode 100644 index 000000000..f786fc773 --- /dev/null +++ b/content/en/docs/2024.9/Reference/troubleshooting/upgrade.md @@ -0,0 +1,11 @@ +--- +title: "Upgrade" +linkTitle: "Upgrade" +description: "Information on troubleshooting {{% ctx %}} Innovation upgrades." +--- + +# {{% param title %}} + +## Troubleshooting issues during upgrade {#ts-during-upgrade} + +{{< workinprogress >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/Tutorials/Administration/_index.md b/content/en/docs/2024.9/Tutorials/Administration/_index.md new file mode 100644 index 000000000..c3a313be9 --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/Administration/_index.md @@ -0,0 +1,48 @@ +--- +title: "Administration" +linkTitle: "Administration" +description: "This section includes tutorials about administering the {{% ctx %}} Innovation platform." +weight: 40 +--- + +## Managing role-based access control + +Shows how to manage role-based access control within Gateway, including assigning access and flow permissions. + +{{< youtube id="v-nll5V4p1Q" >}} + +## Exporting flows + +Shows how to export a set of flows as a `.studiopkg` file. + +{{< youtube id="ZpnDmiuTc8o" >}} + +## Importing flows + +Shows how to import a set of flows from a `.studiopkg` file. + +{{< youtube id="_A4CuCKZuys" >}} + +## Creating packages + +Shows how to create a release package containing all the flows required for your self-contained automation solution. + +{{< youtube id="dzcjU0Ca7EY" >}} + +## Publishing packages + +Shows how to publish a release package into your runtime environment. + +{{< youtube id="iWXMhgPMeHg" >}} + +## Managing package versions + +Shows how to create new versions of a release package, including adding flows, updating flow versions, and removing flows. + +{{< youtube id="lrJMOKyRnGY" >}} + +## Setting default packages + +Shows how to set the default package and the default version of each package. + +{{< youtube id="th-OPwfQ7Vo" >}} diff --git a/content/en/docs/2024.9/Tutorials/Development/_index.md b/content/en/docs/2024.9/Tutorials/Development/_index.md new file mode 100644 index 000000000..4b9c22d5f --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/Development/_index.md @@ -0,0 +1,120 @@ +--- +title: "Development" +linkTitle: "Development" +description: "This section includes tutorials about developing automation using the {{% ctx %}} Innovation platform." +weight: 30 +--- + +## Signing in and out of Gateway + +Shows how to sign in and out of {{% ctx %}} Gateway. + +{{< youtube id="DlgFfkE2LOY" >}} + +## Overview of Gateway + +Shows a high-level overview of {{% ctx %}} Gateway. + +{{< youtube id="EZoUUiv3EpM" >}} + +## Creating groups and moving flows + +Shows how to create new groups, and move existing flows between groups. + +{{< youtube id="fE0dyRoc1Os" >}} + +## Creating and interacting with flows + +Shows how to create a flow, and provides an overview of commonly used features of the flow editor. + +{{< youtube id="zFug1mUwXA8" >}} + +## Interacting with blocks + +Shows how to add, connect, copy, cut, paste, and delete blocks. + +{{< youtube id="vdhZ8opqU8A" >}} + +## Configuring variables + +Shows how to create and configure variables. + +{{< youtube id="AGDdFvRST5k" >}} + +## Configuring blocks + +Shows how to configure blocks using the Properties Editor. + +{{< youtube id="OZrydwUDzuU" >}} + +## Handling exceptions at the block level + +Shows how to handle exceptions at the block level. + +{{< youtube id="abFwXiOR1XQ" >}} + +## Handling exceptions at the workspace level + +Shows how to handle exceptions at the workspace level. + +{{< youtube id="Q_KrAhuyt38" >}} + +## Handling exceptions at the flow level + +Shows how to handle exceptions at the flow level. + +{{< youtube id="S-scB8rV1hw" >}} + +## Throwing exceptions + +Shows how to throw an exception within a flow. + +{{< youtube id="Gt3dSdWNQa4" >}} + +## Debugging a flow + +Shows how to start debugging a flow. + +{{< youtube id="reDYeeAiEYU" >}} + +## Adding and removing breakpoints + +Shows how to add and remove breakpoints when debugging a flow. + +{{< youtube id="8qJRCdz0CpU" >}} + +## Editing a flow whilst debugging + +Shows how to edit a flow whilst debugging, including fixing a runtime exception. + +{{< youtube id="DKrDZxpv9nY" >}} + +## Interacting with version control + +Shows how to save, commit, get master, and compare versions of a flow. + +{{< youtube id="oAfu7DsVgDM" >}} + +## Interacting with version control (multiple flows) + +Shows how to perform commit or get master of multiple flows. + +{{< youtube id="JPdFjeReYQE" >}} + +## Starting a published flow + +Shows how to start a flow, in the default package, via the API Gateway Service using an HTTP request. + +{{< youtube id="IXg0lnKg1BM" >}} + +## Starting a published flow (specific package) + +Shows how to start a flow, in a specific package, via the API Gateway Service using an HTTP request. + +{{< youtube id="8G0N7E9oTvo" >}} + +## Configuring input and output variables + +Shows how to configure the input and output variables of a flow. + +{{< youtube id="5YLg6f4HaBo" >}} diff --git a/content/en/docs/2024.9/Tutorials/Installation/_index.md b/content/en/docs/2024.9/Tutorials/Installation/_index.md new file mode 100644 index 000000000..bbda3ebf6 --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/Installation/_index.md @@ -0,0 +1,8 @@ +--- +title: "Installation" +linkTitle: "Installation" +description: "This section includes tutorials about installing the {{% ctx %}} Innovation platform." +weight: 10 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Tutorials/Setup/_index.md b/content/en/docs/2024.9/Tutorials/Setup/_index.md new file mode 100644 index 000000000..8ddd1ba59 --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/Setup/_index.md @@ -0,0 +1,8 @@ +--- +title: "Setup" +linkTitle: "Setup" +description: "This section includes tutorials about post-installation setup of the {{% ctx %}} Innovation platform." +weight: 20 +--- + +{{< workinprogress >}} diff --git a/content/en/docs/2024.9/Tutorials/Troubleshooting/_index.md b/content/en/docs/2024.9/Tutorials/Troubleshooting/_index.md new file mode 100644 index 000000000..d7120fa05 --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/Troubleshooting/_index.md @@ -0,0 +1,18 @@ +--- +title: "Troubleshooting" +linkTitle: "Troubleshooting" +description: "This section includes tutorials about troubleshooting the {{% ctx %}} Innovation platform." +weight: 50 +--- + +## Errors when starting published flows + +When making requests to start published flows, you may encounter errors. The videos below will show you how to fix them. + +### FlowNotFound + +{{< youtube id="1vXswyCAfn4" >}} + +### InvalidInputVariables + +{{< youtube id="0KIksXI8NLU" >}} diff --git a/content/en/docs/2024.9/Tutorials/_index.md b/content/en/docs/2024.9/Tutorials/_index.md new file mode 100644 index 000000000..03d694711 --- /dev/null +++ b/content/en/docs/2024.9/Tutorials/_index.md @@ -0,0 +1,6 @@ +--- +title: "Tutorials" +linkTitle: "Tutorials" +description: "This section includes all tutorials for the {{% ctx %}} Innovation platform." +weight: 10 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/Whats New/_index.md b/content/en/docs/2024.9/Whats New/_index.md new file mode 100644 index 000000000..b9c72c75c --- /dev/null +++ b/content/en/docs/2024.9/Whats New/_index.md @@ -0,0 +1,125 @@ +--- +title: "What's New?" +linkTitle: "What's New?" +description: "Discover what's new in the {{% ctx %}} platform." +weight: 1 +--- + +## Summary + +2024.9 is the second [Release][] of the next generation of {{% ctx %}} and improves on the [2024.7][] release in the following areas: + +* [Capability][] +* [Observability][] +* [Scalability][] +* [Security][] +* [Usability][] +* [Third-Party Support][] +* [Installation][] +* [Upgrade][] +* [Documentation][] + +## Improved Capability + +This release introduces multiple new features to the {{% ctx %}} platform: + +* The concept of [Process and Activity][], which are types of [Flow][], has now been introduced to {{% ctx %}} Gateway. +* [Saving Output Properties to multiple variables][] is now supported. +* A new built-in [execution context variable][] has been added to the Flow Engine which contains the initiator. +* A new [Proxy for the {{% ctx %}} 7 Flow API][] has been added to the platform. + +## Improved Observability + +Observability has been improved by [adding logging to blocks that communicate with external systems][Logging added to blocks that communicate with external systems]. + +## Improved Scalability + +Optimisation to scalability has been made by [reducing the total number of NServiceBus endpoints and RabbitMQ queues][Reduction of total number of NServiceBus endpoints and RabbitMQ queues]. + +## Improved Security + +We increased the security of the platform by: + +* [Upgrading the OpenSSL version][Upgrade OpenSSL] shipped with the platform. +* Added [Multi-domain certificates support][]. +* A [CortexManagementUser for RabbitMQ is now created during upgrade][New CortexManagementUser added to manage RabbitMQ queues]. +* [Server-side validation added to {{% ctx %}} Gateway API][] to prevent [Path Traversal][] attacks. +* Removal of the [refresh token cookie on sign out][remove refresh token cookie on sign out]. + +## Improved Usability + +The usability of the platform has been improved by: + +* Renaming the [Flows Charm to Dev and changing the icon][Rename Flows Charm to Dev and change icon]. +* Renaming the [Settings Charm to Admin and changing the icon][Rename Settings Charm to Admin and change icon]. + +## Improved Third-Party Support + +Third-party Support has been improved by [upgrading the platform to .NET 8][Upgrade to .NET 8]. + +## Improved Installation + +Installation when [files are blocked by the operating system][Support installation when files are blocked by the operating system] due to the `Zone.Identifier` is now supported. + +## Improved Upgrade + +The upgrade process has been improved by: + +* [Supporting upgrade when files are blocked by the operating system][Support upgrade when files are blocked by the operating system]. +* Upgrading the [Execution Service when the engine version is unchanged][Execution Service is upgraded when the engine version is unchanged]. +* [Handling of the Execution Services lifecycle events][]. + +## Improved Documentation + +The documentation includes updates related to: + +* New concepts such as [Process and Activity][Process and Activity Documentation] as well as [Decomposition of Output properties][]. +* [Preventing deadlocks when using semaphores][Prevent deadlocks when using semaphores]. +* [Updating screenshots][screenshots updated] to reflect the new branding. +* [Flow compatibility version][Flow compatibility version introduced] being added to the release notes. +* [General improvements to the documentation][]. + +For a full list of what has been introduced in this release, please see the [2024.9 Release Notes][] + +[Release]: {{< url path="Cortex.Reference.Glossary.P-T.Release" version="2024.9" >}} +[2024.7]: {{< url path="Cortex.Blogs.Releases.2024.7.MainDoc" version="2024.9" >}} + +[Capability]: {{< ref "#improved-capability" >}} +[Observability]: {{< ref "#improved-observability" >}} +[Scalability]: {{< ref "#improved-scalability" >}} +[Security]: {{< ref "#improved-security" >}} +[Usability]: {{< ref "#improved-usability" >}} +[Third-Party Support]: {{< ref "#improved-third-party-support" >}} +[Installation]: {{< ref "#improved-installation" >}} +[Upgrade]: {{< ref "#improved-upgrade" >}} +[Documentation]: {{< ref "#improved-documentation" >}} + +[Process and Activity]: {{< url path="Cortex.Blogs.Releases.2024.9.ProcessAndActivity" version="2024.9" >}} +[Saving Output Properties to multiple variables]: {{< url path="Cortex.Blogs.Releases.2024.9.SaveOutputPropertiesToMultipleVariables" version="2024.9" >}} +[execution context variable]: {{< url path="Cortex.Blogs.Releases.2024.9.ExecutionContextVariable" version="2024.9" >}} +[Proxy for the {{% ctx %}} 7 Flow API]: {{< url path="Cortex.Blogs.Releases.2024.9.ProxyForTheCortex7FlowApi" version="2024.9" >}} +[Logging added to blocks that communicate with external systems]: {{< url path="Cortex.Blogs.Releases.2024.9.LoggingAddedToBlocksThatCommunicateWithExternalSystems" version="2024.9" >}} +[Reduction of total number of NServiceBus endpoints and RabbitMQ queues]: {{< url path="Cortex.Blogs.Releases.2024.9.ReductionOfTotalNumberOfNServiceBusEndpointsAndRabbitMQQueues" version="2024.9" >}} +[Upgrade OpenSSL]: {{< url path="Cortex.Blogs.Releases.2024.9.UpgradeOpenSSL" version="2024.9" >}} +[Multi-domain certificates support]: {{< url path="Cortex.Blogs.Releases.2024.9.MultiDomainCertificatesSupport" version="2024.9" >}} +[New CortexManagementUser added to manage RabbitMQ queues]: {{< url path="Cortex.Blogs.Releases.2024.9.NewCortexManagementUserAddedToManageRabbitMQQueues" version="2024.9" >}} +[Server-side validation added to {{% ctx %}} Gateway API]: {{< url path="Cortex.Blogs.Releases.2024.9.ServerSideValidationAddedToCortexGatewayAPI" version="2024.9" >}} +[Remove refresh token cookie on sign out]: {{< url path="Cortex.Blogs.Releases.2024.9.RemoveRefreshTokenCookieOnSign" version="2024.9" >}} +[Rename Flows Charm to Dev and change icon]: {{< url path="Cortex.Blogs.Releases.2024.9.RenameFlowsCharmToDevAndChangeIcon" version="2024.9" >}} +[Rename Settings Charm to Admin and change icon]: {{< url path="Cortex.Blogs.Releases.2024.9.RenameSettingsCharmToAdminAndChangeIcon" version="2024.9" >}} +[Upgrade to .NET 8]: {{< url path="Cortex.Blogs.Releases.2024.9.UpgradeToNet8" version="2024.9" >}} +[Support installation when files are blocked by the operating system]: {{< url path="Cortex.Blogs.Releases.2024.9.SupportInstallationWhenFilesAreBlockedByTheOperatingSystem" version="2024.9" >}} +[Support upgrade when files are blocked by the operating system]: {{< url path="Cortex.Blogs.Releases.2024.9.SupportUpgradeWhenFilesAreBlockedByTheOperatingSystem" version="2024.9" >}} +[Execution Service is upgraded when the engine version is unchanged]: {{< url path="Cortex.Blogs.Releases.2024.9.ExecutionServiceIsUpgradedWhenTheEngineVersionIsUnchanged" version="2024.9" >}} +[Handling of the Execution Services lifecycle events]: {{< url path="Cortex.Blogs.Releases.2024.9.HandlingOfTheExecutionServicesLifecycleEvents" version="2024.9" >}} +[Process and Activity Documentation]: {{< url path="Cortex.Blogs.Releases.2024.9.ProcessAndActivityDocumentation" version="2024.9" >}} +[Decomposition of Output properties]: {{< url path="Cortex.Blogs.Releases.2024.9.DecompositionOfOutputProperties" version="2024.9" >}} +[Prevent deadlocks when using semaphores]: {{< url path="Cortex.Blogs.Releases.2024.9.PreventDeadlocksWhenUsingSemaphores" version="2024.9" >}} +[Screenshots updated]: {{< url path="Cortex.Blogs.Releases.2024.9.ScreenshotsUpdated" >}} +[Flow compatibility version introduced]: {{< url path="Cortex.Blogs.Releases.2024.9.FlowCompatibilityVersionIntroduced" version="2024.9" >}} +[General improvements to the documentation]: {{< url path="Cortex.Blogs.Releases.2024.9.GeneralImprovementsToTheDocumentation" version="2024.9" >}} + +[2024.9 Release Notes]: {{< url path="Cortex.Blogs.Releases.2024.9.MainDoc" version="2024.9" >}} + +[Flow]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow.MainDoc" version="2024.9" >}} +[Path Traversal]: {{< url path="Owasp.PathTraversal.MainDoc" version="2024.9" >}} diff --git a/content/en/docs/2024.9/_index.md b/content/en/docs/2024.9/_index.md new file mode 100644 index 000000000..d9e39d0d6 --- /dev/null +++ b/content/en/docs/2024.9/_index.md @@ -0,0 +1,6 @@ +--- +title: "2024.9" +linkTitle: "2024.9" +description: "Product documentation for the {{% ctx %}} automation platform, including guides, tutorials and reference documentation." +weight: 990 +--- diff --git a/content/en/docs/2024.9/_shared/_index.md b/content/en/docs/2024.9/_shared/_index.md new file mode 100644 index 000000000..3d65eaa0f --- /dev/null +++ b/content/en/docs/2024.9/_shared/_index.md @@ -0,0 +1,3 @@ +--- +headless: true +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/advanced/ssl-best-practices.md b/content/en/docs/2024.9/_shared/advanced/ssl-best-practices.md new file mode 100644 index 000000000..a0d3cf414 --- /dev/null +++ b/content/en/docs/2024.9/_shared/advanced/ssl-best-practices.md @@ -0,0 +1,79 @@ +These are non-compulsory security measures, recommended to be applied to the servers, in order to prevent potential attacks that exploit known industry security vulnerabilities. + +Applying these measures may impact other applications running on your server. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes. + +A collection of registry settings can be applied during installation to guarantee your server is only using the recommended encryption algorithms and TLS protocols: + +| Type | Name | Enabled | +| --------------------- | ----------------------------------------| ----------- | +| Ciphers | AES 128/128 | ✓ | +| | AES 256/256 | ✓ | +| | Triple DES 168 | ✓ | +| | DES 56/56 | ✕ | +| | NULL | ✕ | +| | RC2 128/128 | ✕ | +| | RC2 40/128 | ✕ | +| | RC2 56/128 | ✕ | +| | RC4 128/128 | ✕ | +| | RC4 40/128 | ✕ | +| | RC4 56/128 | ✕ | +| | RC4 64/128 | ✕ | +| | | | +| Hashes | MD5 | ✕ | +| | SHA | ✓ | +| | SHA256 | ✓ | +| | SHA384 | ✓ | +| | SHA512 | ✓ | +| | | | +| KeyExchangeAlgorithms | Diffie-Hellman | ✓ | +| | ECDH | ✓ | +| | PKCS | ✓ | +| | | | +| Protocols | Multi-Protocol Unified Hello | ✕ | +| | PCT 1.0 | ✕ | +| | SSL 2.0 | ✕ | +| | SSL 3.0 | ✕ | +| | TLS 1.0 | ✕ | +| | TLS 1.1 | ✕ | +| | TLS 1.2 | ✓ | +| | | | +| Cipher Suites | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ✓ | +| | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ✓ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA25 | ✕ | +| | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_RSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_RSA_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_256_CBC_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_RSA_WITH_3DES_EDE_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 | ✕ | +| | TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_DHE_DSS_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA | ✕ | +| | TLS_RSA_WITH_RC4_128_SHA | ✕ | +| | TLS_RSA_WITH_RC4_128_MD5 | ✕ | +| | TLS_RSA_WITH_NULL_SHA256 | ✕ | +| | TLS_RSA_WITH_NULL_SHA | ✕ | +| | TLS_PSK_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_PSK_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_PSK_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_PSK_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_PSK_WITH_NULL_SHA384 | ✕ | +| | TLS_PSK_WITH_NULL_SHA256 | ✕ | + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on {{% ctx %}} components themselves as well as their communication capabilities with third party systems and services, e.g. Execution Service executing flows with blocks which communicate with 3rd parties via PowerShell or REST. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} diff --git a/content/en/docs/2024.9/_shared/architecture/components/multi-server.md b/content/en/docs/2024.9/_shared/architecture/components/multi-server.md new file mode 100644 index 000000000..216927df2 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/multi-server.md @@ -0,0 +1,53 @@ +| Component | Purpose | Required/Optional | Server Role | +|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------|--------------------------------------------| +| [{{% ctx %}} Gateway][Gateway Guide] | {{< section "/architecture/components/purpose/cortex-gateway.md" >}} | Required | Web Application Server | +| [{{% ctx %}} Studio][Studio Guide] | {{< section "/architecture/components/purpose/cortex-studio.md" >}} | Required | Web Application Server | +| [{{% ctx %}} Innovation Core Application][Innovation Core Application] | {{< section "/architecture/components/purpose/cortex-innovation-core-application.md" >}} | Required | Application Server | +|     > [API Gateway Service][API Gateway Service] | {{< section "/architecture/components/purpose/api-gateway-service.md" >}} | - | - | +|     > [Authorisation Service][Authorisation Service] | {{< section "/architecture/components/purpose/authorisation-service.md" >}} | - | - | +|     > [Concurrency Management Service][Concurrency Management Service] | {{< section "/architecture/components/purpose/concurrency-management-service.md" >}} | - | - | +|     > [Configuration Management Service][Configuration Management Service] | {{< section "/architecture/components/purpose/configuration-management-service.md" >}} | - | - | +|     > [Data Storage Service][Data Storage Service] | {{< section "/architecture/components/purpose/data-storage-service.md" >}} | - | - | +|     > [Execution Management Service][Execution Management Service] | {{< section "/architecture/components/purpose/execution-management-service.md">}} | - | - | +|     > [Licence Management Service][Licence Management Service] | {{< section "/architecture/components/purpose/licence-management-service.md" >}} | - | - | +|     > [Listeners Service][Listeners Service] | {{< section "/architecture/components/purpose/listeners-service.md" >}} | - | - | +|     > [Package Management Service][Package Management Service] | {{< section "/architecture/components/purpose/package-management-service.md" >}} | - | - | +|     > [Provisioning Service][Provisioning Service] | {{< section "/architecture/components/purpose/provisioning-service.md" >}} | - | - | +|     > [Scheduling Service][Scheduling Service] | {{< section "/architecture/components/purpose/scheduling-service.md" >}} | - | - | +|     > [Triggers Service][Triggers Service] | {{< section "/architecture/components/purpose/triggers-service.md" >}} | - | - | +| [{{% ctx %}} Innovation Execution Application][Innovation Execution Application] | {{< section "/architecture/components/purpose/cortex-innovation-execution-application.md" >}} | Required | Application Server | +|     > [Execution Service][Execution Service] | {{< section "/architecture/components/purpose/execution-service.md" >}} | - | - | +| {{% ctx %}} Block Packages | {{< section "/architecture/components/purpose/cortex-block-packages.md" >}} | Required | Web Application Server, Application Server | +| [Microsoft Service Fabric][] | {{< section "/architecture/components/purpose/ms-service-fabric.md" >}} | Required | Application Server | +| [Microsoft Service Fabric Explorer][] | {{< section "/architecture/components/purpose/ms-service-fabric-explorer.md" >}} | Required | Application Server | +| [Particular NServiceBus][] | {{< section "/architecture/components/purpose/particular-nservicebus.md" >}} | Required | Application Server | +| [Pivotal RabbitMQ][] | {{< section "/architecture/components/purpose/pivotal-rabbitmq.md" >}} | Required | Application Server | +| [Erlang OTP][] | {{< section "/architecture/components/purpose/erlang-otp.md" >}} | Required | Application Server | +| [gobetween][] | {{< section "/architecture/components/purpose/gobetween.md" >}} | Required | Load Balancer | +| [NSSM][] | {{< section "/architecture/components/purpose/nssm.md" >}} | Required | Load Balancer | + +[Innovation Core Application]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.MainDoc" >}} +[Innovation Execution Application]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.MainDoc" >}} + +[API Gateway Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[Authorisation Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.AuthorisationService.MainDoc" >}} +[Concurrency Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConcurrencyManagementService.MainDoc" >}} +[Configuration Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConfigurationManagementService.MainDoc" >}} +[Data Storage Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc" >}} +[Execution Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ExecutionManagementService.MainDoc" >}} +[Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" >}} +[Licence Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.LicenceManagementService.MainDoc" >}} +[Listeners Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ListenersService.MainDoc" >}} +[Package Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.PackageManagementService.MainDoc" >}} +[Provisioning Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ProvisioningService.MainDoc" >}} +[Scheduling Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.SchedulingService.MainDoc" >}} +[Triggers Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.TriggersService.MainDoc" >}} +[Gateway Guide]: {{< url path="Cortex.Guides.Gateway.MainDoc" >}} +[Studio Guide]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Microsoft Service Fabric]: {{< url path="MSDocs.ServiceFabric.MainDoc" >}} +[Microsoft Service Fabric Explorer]: {{< url path="MSDocs.ServiceFabric.Explorer" >}} +[Particular NServiceBus]: {{< url path="Particular.NServiceBus.MainDoc" >}} +[Pivotal RabbitMQ]: {{< url path="RabbitMQ.MainDoc" >}} +[Erlang OTP]: {{< url path="ErlangOTP.MainDoc" >}} +[gobetween]: {{< url path="GoBetween.MainDoc" >}} +[NSSM]: {{< url path="NSSM.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/architecture/components/node-details.md b/content/en/docs/2024.9/_shared/architecture/components/node-details.md new file mode 100644 index 000000000..368ebcd10 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/node-details.md @@ -0,0 +1,3 @@ +Where a node contains the following: + +{{< figure src="/images/editable/Cortex Innovation Node Details.png" class="centre" title="Node details" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/api-gateway-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/api-gateway-service.md new file mode 100644 index 000000000..6dd993c28 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/api-gateway-service.md @@ -0,0 +1 @@ +Application Service that routes client requests to the correct distributed {{% ctx %}} Innovation services. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/authorisation-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/authorisation-service.md new file mode 100644 index 000000000..7116f4a2a --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/authorisation-service.md @@ -0,0 +1 @@ +Application Service that authorises users to send API requests. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/concurrency-management-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/concurrency-management-service.md new file mode 100644 index 000000000..1eda9fba5 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/concurrency-management-service.md @@ -0,0 +1 @@ +Application Service that stores and manages concurrent access to resources used by executions within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/configuration-management-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/configuration-management-service.md new file mode 100644 index 000000000..a30ef1f04 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/configuration-management-service.md @@ -0,0 +1 @@ +Application Service that stores and distributes configuration data to services within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-block-packages.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-block-packages.md new file mode 100644 index 000000000..593d8b8a1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-block-packages.md @@ -0,0 +1 @@ +A set of files that contain the blocks that users can use to build flows. Used by the Execution Service. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway-databases.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway-databases.md new file mode 100644 index 000000000..45380eb0d --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway-databases.md @@ -0,0 +1 @@ +A set of databases created automatically by Gateway which are used for storing data related to user roles, flows, etc. Hopefully, we can remove the need for Gateway Databases in the next release. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway.md new file mode 100644 index 000000000..fa2132d34 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-gateway.md @@ -0,0 +1 @@ +Web portal that hosts applications for creating automation solutions and managing their full life-cycle, including design, development, testing, deployment, monitoring, maintenance and ultimately end-of-life. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-core-application.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-core-application.md new file mode 100644 index 000000000..61d36e55e --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-core-application.md @@ -0,0 +1 @@ +The Service Fabric application that is hosting the core services required by {{% ctx %}} Innovation. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-execution-application.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-execution-application.md new file mode 100644 index 000000000..5a72f451a --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-innovation-execution-application.md @@ -0,0 +1 @@ +The Service Fabric application that is hosting the services executing {{% ctx %}} Innovation automation flows. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-studio.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-studio.md new file mode 100644 index 000000000..c93afb1e7 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/cortex-studio.md @@ -0,0 +1 @@ +Application hosted in {{% ctx %}} Gateway that provides the graphical, low-code environment for developing, testing, versioning, publishing and managing the full life-cycle of automation solutions. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/data-storage-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/data-storage-service.md new file mode 100644 index 000000000..71006dac1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/data-storage-service.md @@ -0,0 +1 @@ +Application Service that can be used to store and retrieve data for executions within in the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/erlang-otp.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/erlang-otp.md new file mode 100644 index 000000000..e246171ce --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/erlang-otp.md @@ -0,0 +1 @@ +Erlang run-time required by the RabbitMQ message broker. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-management-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-management-service.md new file mode 100644 index 000000000..6301f12db --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-management-service.md @@ -0,0 +1 @@ +Application Service that stores information related to executions currently running within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-service.md new file mode 100644 index 000000000..f8ffead92 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/execution-service.md @@ -0,0 +1 @@ +Application Service that executes automation flows. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/gobetween.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/gobetween.md new file mode 100644 index 000000000..729d4e358 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/gobetween.md @@ -0,0 +1 @@ +L4 load balancer and reverse proxy used to load balance requests between clustered instances of {{% ctx %}} Innovation services. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/licence-management-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/licence-management-service.md new file mode 100644 index 000000000..5a9f8cd5b --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/licence-management-service.md @@ -0,0 +1 @@ +Application Service that validates and distributes licences to services within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/listeners-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/listeners-service.md new file mode 100644 index 000000000..225dd2dac --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/listeners-service.md @@ -0,0 +1 @@ +Application Service that accepts incoming connections that could trigger executions. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric-explorer.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric-explorer.md new file mode 100644 index 000000000..087f922e1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric-explorer.md @@ -0,0 +1 @@ +Web portal for monitoring and managing the Service Fabric instance that automation solutions are deployed to. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric.md new file mode 100644 index 000000000..ad370fe37 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-service-fabric.md @@ -0,0 +1 @@ +Distributed systems platform that hosts the {{% ctx %}} Innovation services where automation solutions are deployed to; provides scalable, reliable and manageable enterprise-grade High Availability (HA) using clustering. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-sql-server.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-sql-server.md new file mode 100644 index 000000000..7a31c1df7 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/ms-sql-server.md @@ -0,0 +1 @@ +Required by {{% ctx %}} Gateway for creating and storing the Gateway Databases. Hopefully, we can remove the need for SQL Server in the next release. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/nssm.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/nssm.md new file mode 100644 index 000000000..9adb741d2 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/nssm.md @@ -0,0 +1 @@ +Windows Service Manager that hosts the gobetween load balancer application as a Windows Service. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/package-management-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/package-management-service.md new file mode 100644 index 000000000..ef521695b --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/package-management-service.md @@ -0,0 +1 @@ +Application Service that handles publishing and unpublishing packages. It also stores package configuration. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/particular-nservicebus.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/particular-nservicebus.md new file mode 100644 index 000000000..dbc0f9641 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/particular-nservicebus.md @@ -0,0 +1 @@ +Messaging platform enabling scalable, reliable and flexible asynchronous messaging between distributed {{% ctx %}} Innovation services. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/pivotal-rabbitmq.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/pivotal-rabbitmq.md new file mode 100644 index 000000000..b7bfe9a74 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/pivotal-rabbitmq.md @@ -0,0 +1 @@ +Message broker used by the NServiceBus messaging platform to transport messages asynchronously between distributed {{% ctx %}} Innovation services using publish/subscribe mechanism. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/provisioning-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/provisioning-service.md new file mode 100644 index 000000000..edec61a76 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/provisioning-service.md @@ -0,0 +1 @@ +Application Service that provisions new services on demand. For example, a new Execution Service is provisioned when a package is published with a new version of block packages. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/scheduling-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/scheduling-service.md new file mode 100644 index 000000000..7bb7e0508 --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/scheduling-service.md @@ -0,0 +1 @@ +Application Service that can be used to schedule executions within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/purpose/triggers-service.md b/content/en/docs/2024.9/_shared/architecture/components/purpose/triggers-service.md new file mode 100644 index 000000000..bcf48f29e --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/purpose/triggers-service.md @@ -0,0 +1 @@ +Application Service that handles automatically triggering executions within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/architecture/components/single-server.md b/content/en/docs/2024.9/_shared/architecture/components/single-server.md new file mode 100644 index 000000000..3bba0f94d --- /dev/null +++ b/content/en/docs/2024.9/_shared/architecture/components/single-server.md @@ -0,0 +1,49 @@ +| Component | Purpose | Required/Optional | Server Role | +|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------|--------------------------------------------| +| [{{% ctx %}} Gateway][Gateway Guide] | {{< section "/architecture/components/purpose/cortex-gateway.md">}} | Required | Web Application Server | +| [{{% ctx %}} Studio][Studio Guide] | {{< section "/architecture/components/purpose/cortex-studio.md" >}} | Required | Web Application Server | +| [{{% ctx %}} Innovation Core Application][Innovation Core Application] | {{< section "/architecture/components/purpose/cortex-innovation-core-application.md" >}} | Required | Application Server | +|     > [API Gateway Service][API Gateway Service] | {{< section "/architecture/components/purpose/api-gateway-service.md" >}} | - | - | +|     > [Authorisation Service][Authorisation Service] | {{< section "/architecture/components/purpose/authorisation-service.md" >}} | - | - | +|     > [Concurrency Management Service][Concurrency Management Service] | {{< section "/architecture/components/purpose/concurrency-management-service.md" >}} | - | - | +|     > [Configuration Management Service][Configuration Management Service] | {{< section "/architecture/components/purpose/configuration-management-service.md" >}} | - | - | +|     > [Data Storage Service][Data Storage Service] | {{< section "/architecture/components/purpose/data-storage-service.md" >}} | - | - | +|     > [Execution Management Service][Execution Management Service] | {{< section "/architecture/components/purpose/execution-management-service.md">}} | - | - | +|     > [Licence Management Service][Licence Management Service] | {{< section "/architecture/components/purpose/licence-management-service.md" >}} | - | - | +|     > [Listeners Service][Listeners Service] | {{< section "/architecture/components/purpose/listeners-service.md" >}} | - | - | +|     > [Package Management Service][Package Management Service] | {{< section "/architecture/components/purpose/package-management-service.md" >}} | - | - | +|     > [Provisioning Service][Provisioning Service] | {{< section "/architecture/components/purpose/provisioning-service.md" >}} | - | - | +|     > [Scheduling Service][Scheduling Service] | {{< section "/architecture/components/purpose/scheduling-service.md" >}} | - | - | +|     > [Triggers Service][Triggers Service] | {{< section "/architecture/components/purpose/triggers-service.md" >}} | - | - | +| [{{% ctx %}} Innovation Execution Application][Innovation Execution Application] | {{< section "/architecture/components/purpose/cortex-innovation-execution-application.md" >}} | Required | Application Server | +|     > [Execution Service][Execution Service] | {{< section "/architecture/components/purpose/execution-service.md" >}} | - | - | +| {{% ctx %}} Block Packages | {{< section "/architecture/components/purpose/cortex-block-packages.md" >}} | Required | Web Application Server, Application Server | +| [Microsoft Service Fabric][] | {{< section "/architecture/components/purpose/ms-service-fabric.md" >}} | Required | Application Server | +| [Microsoft Service Fabric Explorer][] | {{< section "/architecture/components/purpose/ms-service-fabric-explorer.md" >}} | Required | Application Server | +| [Particular NServiceBus][] | {{< section "/architecture/components/purpose/particular-nservicebus.md" >}} | Required | Application Server | +| [Pivotal RabbitMQ][] | {{< section "/architecture/components/purpose/pivotal-rabbitmq.md" >}} | Required | Application Server | +| [Erlang OTP][] | {{< section "/architecture/components/purpose/erlang-otp.md" >}} | Required | Application Server | + +[Innovation Core Application]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.MainDoc" >}} +[Innovation Execution Application]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.MainDoc" >}} + +[API Gateway Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ApiGatewayService.MainDoc" >}} +[Authorisation Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.AuthorisationService.MainDoc" >}} +[Concurrency Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConcurrencyManagementService.MainDoc" >}} +[Configuration Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ConfigurationManagementService.MainDoc" >}} +[Data Storage Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.DataStorageService.MainDoc" >}} +[Execution Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ExecutionManagementService.MainDoc" >}} +[Execution Service]: {{< url path="Cortex.Guides.CortexInnovation.ExecutionApplication.Services.ExecutionService.MainDoc" >}} +[Licence Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.LicenceManagementService.MainDoc" >}} +[Listeners Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ListenersService.MainDoc" >}} +[Package Management Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.PackageManagementService.MainDoc" >}} +[Provisioning Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.ProvisioningService.MainDoc" >}} +[Scheduling Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.SchedulingService.MainDoc" >}} +[Triggers Service]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.TriggersService.MainDoc" >}} +[Gateway Guide]: {{< url path="Cortex.Guides.Gateway.MainDoc" >}} +[Studio Guide]: {{< url path="Cortex.Guides.Studio.MainDoc" >}} +[Microsoft Service Fabric]: {{< url path="MSDocs.ServiceFabric.MainDoc" >}} +[Microsoft Service Fabric Explorer]: {{< url path="MSDocs.ServiceFabric.Explorer" >}} +[Particular NServiceBus]: {{< url path="Particular.NServiceBus.MainDoc" >}} +[Pivotal RabbitMQ]: {{< url path="RabbitMQ.MainDoc" >}} +[Erlang OTP]: {{< url path="ErlangOTP.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/currentVersion.md b/content/en/docs/2024.9/_shared/currentVersion.md new file mode 100644 index 000000000..9bc54a862 --- /dev/null +++ b/content/en/docs/2024.9/_shared/currentVersion.md @@ -0,0 +1 @@ +2024.9 \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/apply-recommended-security-measures.md b/content/en/docs/2024.9/_shared/install-application-server/apply-recommended-security-measures.md new file mode 100644 index 000000000..045b8aea6 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/apply-recommended-security-measures.md @@ -0,0 +1,36 @@ +These are non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities. + +Applying these measures may impact other applications running on your server. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes. + +### Only Use Recommended Encryption Algorithms and TLS Protocols + +A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at [SSL Best Practices][]. + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on {{% ctx %}} components themselves as well as their communication capabilities with third party systems and services, e.g. Execution Service executing flows with blocks which communicate with 3rd parties via PowerShell or REST. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} + +The settings can be applied by running a script. Be aware that the server will be restarted when the script is run. Apply the settings by following these instructions: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Install.SSLBestPractices.ps1` script using the following command: + + ```powershell + .\Cortex.Innovation.Install.SSLBestPractices.ps1 + ``` + + {{% alert title="Note" %}} +To avoid answering all of the prompts `-Override 0` can be added to the end of the script. This will automatically apply all settings and forcibly restart the server. + {{% /alert %}} + + If `-Override 0` has been specified no further steps need to be taken and you can move on to the next section when the server has restarted. +1. To use all the recommended settings click `Apply all` to the first prompt. + + To selectively apply each setting select `Choose which to apply`. Each change will then be prompted with a Yes/No confirmation before applying. +1. Restart the machine when the script asks. + +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/install-dot-net-framework.md b/content/en/docs/2024.9/_shared/install-application-server/install-dot-net-framework.md new file mode 100644 index 000000000..30964ad61 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/install-dot-net-framework.md @@ -0,0 +1,17 @@ +Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.2 to be installed on the server. + +To find the version of the framework that is installed: + +1. On the Start menu, choose `Run`. +1. In the open box, enter `regedit.exe`. You must have administrative credentials to run regedit.exe. +1. In the Registry Editor, open the subkey `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full`. +1. If the `Full` subkey is not present, then you do not have the .NET Framework 4.5 or later installed. +1. Check for a `DWORD` value named `Release`. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is `461808` or over then at least .NET Framework 4.7.2 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it. + +To install .NET Framework 4.7.2: + +1. Download the [.NET Framework 4.7.2][NET Framework 472] installer. +1. Double-click on the installer file to run it. +1. Follow the wizard to complete the installation. + +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/install-application-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/install-application-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..4371a34ad --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/make-installation-artefacts-available.md @@ -0,0 +1,6 @@ +1. Copy the following artefacts to a folder on the server: + * Cortex Innovation {{< version >}} - Block Packages.zip + * Cortex Innovation {{< version >}} - App Services.zip + * Cortex Innovation {{< version >}} - App Server Install Scripts.zip + +1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/install-application-server/multi-server/check-application-services.md b/content/en/docs/2024.9/_shared/install-application-server/multi-server/check-application-services.md new file mode 100644 index 000000000..5bd78e8c6 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/multi-server/check-application-services.md @@ -0,0 +1,37 @@ +1. Log on to one of the Application Servers. +1. Import the client certificate, used in the `ClientCertificatePath` parameter of the [Configure Installation Script][] section, to your Current User certificate store. This can be achieved by double-clicking on the client certificate .PFX file and following the wizard. + + If using self-signed certificates, the certificate can be retrieved by using the `Manage Computer Certificates` tool in Windows to export the `CortexServerCertificate` from the `Personal` store as a pfx file and then importing it to the `Current User` store by double-clicking on it and following the wizard. The certificate must also be imported to `Trusted Root Certification Authorities` in the `Local Computer` store. +1. Open a web browser. +1. Navigate to `https://app-server.domain.com:9080/Explorer`, where `app-server.domain.com` is the fully qualified domain name of any Application Server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration. + + The screen should resemble that in the following figure: + {{< figure src="/images/Service Fabric Explorer.png" >}} + + The status circles should be entirely green - this indicates that all nodes, services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system. + + After expanding the application, clicking on any of the services should display a green circle and `Status = Active`: + + {{< figure src="/images/Service Fabric Explorer - Service.png" >}} + + After expanding either of the services, clicking on any of the instances/partitions should display a green circle and `Status = Ready`: + + {{< figure src="/images/Service Fabric Explorer - Instance.png" >}} + + Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and `Status = Up`: + + {{< figure src="/images/Service Fabric Explorer - Node.png" >}} + + If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section. + + If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong. + + If no useful message can be seen here, the service log files may contain more information. These can be found on each Application Server at: + + * `%ProgramData%/Cortex/API Gateway Service/Logs` + * `%ProgramData%/Cortex/Execution Service/Logs` + + If no solution can be found, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +[Configure Installation Script]: {{< ref "#configure-installation-script" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/add-antivirus-exclusions.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-antivirus-exclusions.md new file mode 100644 index 000000000..6596c4aa1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-antivirus-exclusions.md @@ -0,0 +1,15 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Add.WindowsDefenderExclusions.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS name or fully qualified domain name of the server: + + ```powershell + .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1") + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. A message will indicate that the script has completed successfully. diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-only/configure-installation-script.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-only/configure-installation-script.md new file mode 100644 index 000000000..a84fafefa --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-only/configure-installation-script.md @@ -0,0 +1,77 @@ +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the App Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`ServerCertificatePath` | The local path of a .PFX certificate file on the server. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the single node cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed later, [when installing Gateway][Install Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigSingleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.CertificateRequirements" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[Install Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-to-7.2/configure-installation-script.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-to-7.2/configure-installation-script.md new file mode 100644 index 000000000..76ff566bf --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-innovation-to-7.2/configure-installation-script.md @@ -0,0 +1,77 @@ +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the App Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed later, [when upgrading Gateway][Upgrade Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed later, [when upgrading Gateway][Upgrade Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`ServerCertificatePath` | The local path of a .PFX certificate file on the server. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the single node cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed later, [when upgrading Gateway][Upgrade Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigSingleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.CertificateRequirements" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[Upgrade Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/add-permissions-to-crypto-folder.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-permissions-to-crypto-folder.md new file mode 100644 index 000000000..039984369 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/add-permissions-to-crypto-folder.md @@ -0,0 +1,14 @@ +Service Fabric requires access to the `C:\ProgramData\Microsoft\Crypto\` folder for the `Network Service` users. + +Grant access to the `Network Service` user following these instructions: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Run the following command: + +```bash +icacls "C:\ProgramData\Microsoft\Crypto\*" /grant *S-1-5-20:RX /t +``` + +{{% alert title="Note" %}} +Some files might fail to be processed with `Access is denied`. This can be ignored. +{{% /alert %}} diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/check-application-services.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/check-application-services.md new file mode 100644 index 000000000..855a61a8f --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/check-application-services.md @@ -0,0 +1,37 @@ +1. Log on to the server. +1. Import the certificate, used in the `ServerCertificatePath` parameter of the [Configure Installation Script][] section, to your `Current User` certificate store. This can be achieved by double-clicking on the certificate .PFX file and following the wizard. + + If using self-signed certificates, the certificate can be retrieved by using the `Manage Computer Certificates` tool in Windows to export the `CortexServerCertificate` from the `Personal` store as a pfx file and then importing it to the `Current User` store by double-clicking on it and following the wizard. The certificate must also be imported to `Trusted Root Certification Authorities` in the `Local Computer` store. +1. Open a web browser. +1. Navigate to `https://server.domain.com:9080/Explorer`, where `server.domain.com` is the fully qualified domain name of the server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration. + + The screen should resemble that in the following figure: + {{< figure src="/images/Service Fabric Explorer - Single.png" >}} + + The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system. + + After expanding the application, clicking on any of the services should display a green circle and `Status = Active`: + + {{< figure src="/images/Service Fabric Explorer - Service - Single.png" >}} + + After expanding either of the services, clicking on any of the instances/partitions should display a green circle and `Status = Ready`: + + {{< figure src="/images/Service Fabric Explorer - Instance - Single.png" >}} + + Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and `Status = Up`: + + {{< figure src="/images/Service Fabric Explorer - Node - Single.png" >}} + + If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section. + + If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong. + + If no useful message can be seen here, the service log files may contain more information. These can be found on the server at: + + * `%ProgramData%/Cortex/API Gateway Service/Logs` + * `%ProgramData%/Cortex/Execution Service/Logs` + + If no solution can be found, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +[Configure Installation Script]: {{< ref "#configure-installation-script" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/check-port-useage.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/check-port-useage.md new file mode 100644 index 000000000..0b1f03420 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/check-port-useage.md @@ -0,0 +1,23 @@ +To check all necessary ports are free, follow these steps. +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Test.PortUsage.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS name or fully qualified domain name of the server: + + ```powershell + .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1") + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. + +1. If all ports are free, the script will report the following: + + `All ports required by Cortex Innovation are free` + + If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the `Cortex.Innovation.Install.Config.json` configuration file, in the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, to use different ports. This will be used later during installation. + + The `Cortex.Innovation.Test.PortUsage.ps1` script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free. diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/run-installation-script.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/run-installation-script.md new file mode 100644 index 000000000..b698abff0 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/run-installation-script.md @@ -0,0 +1,31 @@ +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install HA Services and the required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from [{{% ctx %}} Service Portal][CORTEX Service Portal]. Press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation. + + In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command: + + ```powershell + .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer + ``` + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Installation][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-application-server/single-server/test-installation-script.md b/content/en/docs/2024.9/_shared/install-application-server/single-server/test-installation-script.md new file mode 100644 index 000000000..36ae69a3a --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-application-server/single-server/test-installation-script.md @@ -0,0 +1,31 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 -WhatIf + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -WhatIf -AcceptEULA + ``` + +1. Run the PowerShell command to test the installation script. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. +1. Wait for the command to finish. It will display the output of the installation command without making any changes to the system. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them. + + If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

If this does not work, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. The `WhatIf` script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with `-WhatIf` (e.g. `Cortex.Innovation.Install.Config-WhatIf.json`). This file can be provided when obtaining support. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/assign-certificate-friendly-name.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/assign-certificate-friendly-name.md new file mode 100644 index 000000000..36dd1b3f6 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/assign-certificate-friendly-name.md @@ -0,0 +1,11 @@ +Once the certificate has been imported, a `Friendly Name` should be assigned which will be used in the [Configure {{% ctx %}} Gateway Installation Script][Configure CORTEX Gateway Installation Script] to enable the installation script to identify the certificate to be used for the website: + +1. Click the Windows button (`Start`). +1. Type `certlm.msc` and press `Enter` to open the Certificate Manager dialog. +1. Expand `Personal` and select `Certificates`. +1. You should see your certificate in this store. +1. Right-click on the certificate and select `Properties`. +1. On the `General` tab in the `Friendly Name` text box, enter a name to be used for the certificate. +1. Click `OK`. + +[Configure CORTEX Gateway Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/configure-debugger-installation-script.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/configure-debugger-installation-script.md new file mode 100644 index 000000000..5dc7fd819 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/configure-debugger-installation-script.md @@ -0,0 +1,78 @@ +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the App Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`ServerCertificatePath` | The local path of a .PFX certificate file on the server. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the single node cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed later, [when installing Gateway][Install Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigSingleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.CertificateRequirements" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.EncryptionRequirements" >}} +[Install Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md new file mode 100644 index 000000000..38e7a5e61 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md @@ -0,0 +1,49 @@ +#### Cortex Blocks Provider Host folder + +Check that the {{% ctx %}} Gateway `Application Pool` user has rights to the `Cortex Blocks Provider Host folder` folder using the following steps: + +1. Navigate to `C:\ProgramData\Cortex` +1. Right-click on the `Cortex Blocks Provider Host` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + +#### Repo folder + +Check that the {{% ctx %}} Gateway `Application Pool` user has rights to the `Repo` folder using the following steps: + +1. Check where the `Repo` folder is located + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. Navigate to the `Repo` folder, not opening it. +1. Right-click on the `Repo` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + +#### Perform an IIS reset + +1. Open a Windows PowerShell (x64) window as administrator. +1. Run the following command: `iisreset`. +1. Wait for the action to complete. diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/licensing.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/licensing.md new file mode 100644 index 000000000..88853d480 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-only/licensing.md @@ -0,0 +1,3 @@ +Ensure that a valid {{% ctx %}} licence file named `Cortex.lic` exists on the Web Application server, in the location `%ProgramData%\Cortex\Licences`. If it does not, follow the instructions located at [Licensing Requirements][]. + +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.LicensingRequirements" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/assign-certificate-friendly-name.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/assign-certificate-friendly-name.md new file mode 100644 index 000000000..e39dc70a4 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/assign-certificate-friendly-name.md @@ -0,0 +1,11 @@ +Once the certificate has been imported, a `Friendly Name` should be assigned which will be used in the [Configure {{% ctx %}} Gateway Installation Script][Configure CORTEX Gateway Installation Script] to enable the installation script to identify the certificate to be used for the website: + +1. Click the Windows button (`Start`). +1. Type `certlm.msc` and press `Enter` to open the Certificate Manager dialog. +1. Expand `Personal` and select `Certificates`. +1. You should see your certificate in this store. +1. Right-click on the certificate and select `Properties`. +1. On the `General` tab in the `Friendly Name` text box, enter a name to be used for the certificate. +1. Click `OK`. + +[Configure CORTEX Gateway Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/configure-debugger-installation-script.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/configure-debugger-installation-script.md new file mode 100644 index 000000000..76ed8a84e --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/configure-debugger-installation-script.md @@ -0,0 +1,78 @@ +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the App Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed later, [when upgrading Gateway][Upgrade Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed later, [when upgrading Gateway][Upgrade Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`ServerCertificatePath` | The local path of a .PFX certificate file on the server. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the single node cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed later, [when upgrading Gateway][Upgrade Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigSingleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.CertificateRequirements" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.EncryptionRequirements" >}} +[Upgrade Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/grant-gateway-user-additional-folder-permissions.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/grant-gateway-user-additional-folder-permissions.md new file mode 100644 index 000000000..d7a476356 --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/grant-gateway-user-additional-folder-permissions.md @@ -0,0 +1,19 @@ +#### Cortex Blocks Provider Host folder + +Check that the {{% ctx %}} Gateway `Application Pool` user has rights to the `Cortex Blocks Provider Host folder` folder using the following steps: + +1. Navigate to `C:\ProgramData\Cortex` +1. Right-click on the `Cortex Blocks Provider Host` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/licensing.md b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/licensing.md new file mode 100644 index 000000000..34a467ecc --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/add-innovation-to-7.2/licensing.md @@ -0,0 +1,3 @@ +Ensure that a valid {{% ctx %}} licence file named `Cortex.lic` exists on the Web Application server, in the location `%ProgramData%\Cortex\Licences`. If it does not, follow the instructions located at [Licensing Requirements][]. + +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.LicensingRequirements" >}} diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/grant-gateway-user-folder-permissions.md b/content/en/docs/2024.9/_shared/install-web-application-server/grant-gateway-user-folder-permissions.md new file mode 100644 index 000000000..b3c483c2f --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/grant-gateway-user-folder-permissions.md @@ -0,0 +1,24 @@ +The following folders require `Modify` permission to allow creating the `NuGet` folders and its `NuGet.Config` file within: + +* `C:\Windows\System32\config\systemprofile\AppData\Roaming` +* `C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming` + +For each folder, perform the following steps: + +1. Navigate to the `AppData` folder. +1. Right-click on the `Roaming` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user that will be used for {{% ctx %}} Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user that will be used for {{% ctx %}} Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. +1. If the `Application Pool` user that will be used for {{% ctx %}} Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. diff --git a/content/en/docs/2024.9/_shared/install-web-application-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/install-web-application-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..908a6a01e --- /dev/null +++ b/content/en/docs/2024.9/_shared/install-web-application-server/make-installation-artefacts-available.md @@ -0,0 +1,10 @@ +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation {{< version >}} - App Services.zip + * Cortex Innovation {{< version >}} - App Server Install Scripts.zip + * Cortex Innovation {{< version >}} - Block Packages.zip + * Cortex Innovation {{< version >}} - Gateway.zip + * Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name. +1. Extract the `Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip` zip file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/api-gateway.md b/content/en/docs/2024.9/_shared/port-requirements/description/api-gateway.md new file mode 100644 index 000000000..4079cb037 --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/api-gateway.md @@ -0,0 +1 @@ +The port providing an entry into the API Gateway service. This is used by {{% ctx %}} Gateway to communicate with the {{% ctx %}} Innovation platform services. **If this is changed then it will be necessary to use the updated value in the** **"****Service Fabric Api Gateway Endpoint****" parameter of SetParameters.xml when configuring {{% ctx %}} Gateway later in this document.** \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/authorisation.md b/content/en/docs/2024.9/_shared/port-requirements/description/authorisation.md new file mode 100644 index 000000000..180d1e06b --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/authorisation.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Authorisation service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/configuration-management.md b/content/en/docs/2024.9/_shared/port-requirements/description/configuration-management.md new file mode 100644 index 000000000..4f9eb7c4c --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/configuration-management.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Configuration Management service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/data-storage.md b/content/en/docs/2024.9/_shared/port-requirements/description/data-storage.md new file mode 100644 index 000000000..2047dfa19 --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/data-storage.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Data Storage service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/execution-management.md b/content/en/docs/2024.9/_shared/port-requirements/description/execution-management.md new file mode 100644 index 000000000..580e0e4de --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/execution-management.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Execution Management service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/execution.md b/content/en/docs/2024.9/_shared/port-requirements/description/execution.md new file mode 100644 index 000000000..e88748ed1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/execution.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Execution service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/licence-management.md b/content/en/docs/2024.9/_shared/port-requirements/description/licence-management.md new file mode 100644 index 000000000..216d66fbc --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/licence-management.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Licence Management service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/package-management.md b/content/en/docs/2024.9/_shared/port-requirements/description/package-management.md new file mode 100644 index 000000000..f8dbaddb4 --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/package-management.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Package Management service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/provisioning.md b/content/en/docs/2024.9/_shared/port-requirements/description/provisioning.md new file mode 100644 index 000000000..2ae9526e8 --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/provisioning.md @@ -0,0 +1 @@ +The ports providing communication between other services and the Provisioning service. These are dynamic ports managed by Service Fabric. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/port-requirements/description/triggers-snmp.md b/content/en/docs/2024.9/_shared/port-requirements/description/triggers-snmp.md new file mode 100644 index 000000000..5372c835f --- /dev/null +++ b/content/en/docs/2024.9/_shared/port-requirements/description/triggers-snmp.md @@ -0,0 +1 @@ +The port providing an entry to receive SNMP traps to trigger executions within the Innovation platform. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/prerequisites/add-innovation-to-7.2/encryption-requirements.md b/content/en/docs/2024.9/_shared/prerequisites/add-innovation-to-7.2/encryption-requirements.md new file mode 100644 index 000000000..e000ef175 --- /dev/null +++ b/content/en/docs/2024.9/_shared/prerequisites/add-innovation-to-7.2/encryption-requirements.md @@ -0,0 +1,3 @@ +Certain sensitive parameters required during installation (e.g. passwords) must be encrypted; other potentially sensitive parameters (e.g. usernames) can be encrypted using the [{{% ctx %}} Encryptor][CORTEX Encrypted] PowerShell module, which uses AES256. Details of whether a parameter must or should be encrypted are specified during the installation steps. + +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/multi-server/encryption-requirements.md b/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/multi-server/encryption-requirements.md new file mode 100644 index 000000000..9c368b9b8 --- /dev/null +++ b/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/multi-server/encryption-requirements.md @@ -0,0 +1,37 @@ +Certain sensitive parameters required during installation (e.g. passwords) must be encrypted; other potentially sensitive parameters (e.g. usernames) can be encrypted using the [{{% ctx %}} Encryptor][CORTEX Encrypted] PowerShell module, which uses AES256. Details of whether a parameter must or should be encrypted are specified during the installation steps. + +Before encrypting parameters, it is required to generate a private key that will be used by the [{{% ctx %}} Encryptor][CORTEX Encrypted] PowerShell module using the following steps: + +Choose one of the Application Servers or the Web Application Server, and copy the `Cortex Innovation {{< version >}} - Encryption Key Generator.zip` artefacts to a folder on it: + +1. Extract the `Cortex Innovation {{< version >}} - Encryption Key Generator.zip` file to a folder with the same name. +1. Open a Windows PowerShell (x64) window as administrator. The administrator must be a domain user that is a member of the local Administrators group on the Application Servers and Web Application Server. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Encryption Key Generator` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Encryption Key Generator" + ``` + +1. Run the `Cortex.Encryption.KeyGeneration.exe` application using the following command, modifying the argument value to contain the NETBIOS names or fully qualified domain names of the Application Servers and Web Application Server: + + ```powershell + .\Cortex.Encryption.KeyGeneration.exe "app-server1, app-server2, app-server3, webapp-server" + ``` + +1. A message similar to the following will indicate that the application has completed successfully: + + ```text + app-server1: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on app-server1 + app-server2: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on app-server2 + app-server3: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on app-server3 + webapp-server: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on webapp-server + Encryption Key: 284BADF55BDDC93A47D7DE8FC2C4DC9B + ``` + +{{% alert title="Important" color="warning" %}}For security reasons the outputted `Encryption Key` should be backed up. If any keys were overwritten then they must be backed up too.{{% /alert %}} + +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/single-server/encryption-requirements.md b/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/single-server/encryption-requirements.md new file mode 100644 index 000000000..95ab65f45 --- /dev/null +++ b/content/en/docs/2024.9/_shared/prerequisites/install-innovation-only/single-server/encryption-requirements.md @@ -0,0 +1,33 @@ +Certain sensitive parameters required during installation (e.g. passwords) must be encrypted; other potentially sensitive parameters (e.g. usernames) can be encrypted using the [{{% ctx %}} Encryptor][CORTEX Encrypted] PowerShell module, which uses AES256. Details of whether a parameter must or should be encrypted are specified during the installation steps. + +Before encrypting parameters, it is required to generate a private key that will be used by the [{{% ctx %}} Encryptor][CORTEX Encrypted] PowerShell module using the following steps: + +Copy the `Cortex Innovation {{< version >}} - Encryption Key Generator.zip` artefacts to a folder on the server: + +1. Extract the `Cortex Innovation {{< version >}} - Encryption Key Generator.zip` file to a folder with the same name. +1. Open a Windows PowerShell (x64) window as administrator. The administrator must be a domain user that is a member of the local Administrators group on the Application Server and Web Application Server. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Encryption Key Generator` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Encryption Key Generator" + ``` + +1. Run the `Cortex.Encryption.KeyGeneration.exe` application using the following command, modifying the argument value to contain the NETBIOS names or fully qualified domain names of the Application Server and Web Application Server: + + ```powershell + .\Cortex.Encryption.KeyGeneration.exe "app-server1" + ``` + +1. A message similar to the following will indicate that the application has completed successfully: + + ```text + app-server: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on app-server + webapp-server: Overwritten Encryption key: EE19EB67F6C2D9E9A5AF6F0CE7822A44 + Encryption key set on webapp-server + Encryption Key: 284BADF55BDDC93A47D7DE8FC2C4DC9B + ``` + +{{% alert title="Important" color="warning" %}}For security reasons the outputted `Encryption Key` should be backed up. If any keys were overwritten then they must be backed up too.{{% /alert %}} + +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/preserve-installation-files.md b/content/en/docs/2024.9/_shared/preserve-installation-files.md new file mode 100644 index 000000000..6e485d456 --- /dev/null +++ b/content/en/docs/2024.9/_shared/preserve-installation-files.md @@ -0,0 +1 @@ +Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates. \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/multi-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/multi-server/run-upgrade-script.md new file mode 100644 index 000000000..3e6c71548 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/multi-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the HA Services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/configure-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/configure-upgrade-script.md new file mode 100644 index 000000000..dd0c8c86e --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/configure-upgrade-script.md @@ -0,0 +1,23 @@ +1. In the `Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Configure the script, changing the parameters according to the details given below: + + ```powershell + .\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.3 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.3 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-app-upgrade-log.txt" + ``` + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..8788e464c --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/make-installation-artefacts-available.md @@ -0,0 +1,6 @@ +1. Copy the following artefacts to a folder on the server: + * Cortex Innovation 2024.3 - Block Packages.zip + * Cortex Innovation 2024.3 - App Services.zip + * Cortex Innovation 2024.3 - App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.3 - App Server Install Scripts.zip` file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/run-upgrade-script.md new file mode 100644 index 000000000..060ee1621 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/single-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.3 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the application services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/upgrade-flows.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/upgrade-flows.md new file mode 100644 index 000000000..341704210 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-application-server/upgrade-flows.md @@ -0,0 +1,28 @@ +On the Web Application Server, copy the `Cortex Innovation 2024.3 - Flows Upgrader.zip` artefacts to a folder on it: +1. Extract the `Cortex Innovation 2024.3 - Flows Upgrader.zip` file to a folder with the same name. +1. Open a Windows PowerShell (x64) window as administrator. The administrator must be a domain user that is a member of the local Administrators group on the Web Application Server. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.3 - Flows Upgrader` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.3 - Flows Upgrader" + ``` + +1. Export the flows to be upgraded from Gateway as a studio package. +1. Run the `Cortex.Upgrade.FlowUpgrader.exe` application using the following command, modifying the argument value to contain the extracted studio package of flows to upgrade: + + ```powershell + .\Cortex.Upgrade.FlowUpgrader.exe "C:\Install\Export.studiopkg" + ``` + +1. A message similar to the following will indicate that the application has completed successfully: + + ```text + Upgrading Flows + Flow Upgraded: Test Flows\TestFlow1.flow + Flow Upgraded: Test Flows\TestFlow3.flow + Flow Upgraded: Test Flows\TestFlow2.flow + Flows Upgraded + Upgraded Studio Package Created: export-28UpgradedTo30.StudioPkg + ``` + +1. A new studio package will be created in the same file path as the package given as the argument with the format `{PackageName}-{PreviousVersion}UpgradedTo{NewVersion}.studiopkg`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/configure-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/configure-gateway-script.md new file mode 100644 index 000000000..e9e8dd039 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/configure-gateway-script.md @@ -0,0 +1,35 @@ +1. In the `Cortex Innovation 2024.3 - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.3 - Gateway.zip" ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation 2024.3 - Gateway.zip` file on the server. | + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false`.| + |`CertificateFriendlyName` | Replace this with the friendly name that is allocated to the certificate that {{% ctx %}} Gateway is currently using.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this to `$false` if you do not require the latest recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this to `$false` if you are not using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +[Security Best Practices]: {{< url path="Cortex.Guides.UpgradeCortex.Advanced.SSLBestPractices" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/run-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/run-gateway-script.md new file mode 100644 index 000000000..73fbdc322 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/run-gateway-script.md @@ -0,0 +1,32 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.3 - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.3 - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the upgrade. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/test-upgrade.md b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/test-upgrade.md new file mode 100644 index 000000000..ef6a57f8b --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.3/upgrade-web-application-server/test-upgrade.md @@ -0,0 +1,28 @@ +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Flows` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Flow` 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][] 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, if those blocks are not displayed see [Troubleshooting][]. A list of block palettes should be displayed down the left hand side: + {{< figure src="../../2024.3/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. Failing that, see [Troubleshooting][]. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Settings` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. See [Troubleshooting][] for more information. + +[Troubleshooting]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/multi-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/multi-server/run-upgrade-script.md new file mode 100644 index 000000000..5771f669c --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/multi-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the HA Services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/configure-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/configure-upgrade-script.md new file mode 100644 index 000000000..3732d2812 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/configure-upgrade-script.md @@ -0,0 +1,23 @@ +1. In the `Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Configure the script, changing the parameters according to the details given below: + + ```powershell + .\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.5 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.5 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-app-upgrade-log.txt" + ``` + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..a6bc4fa80 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/make-installation-artefacts-available.md @@ -0,0 +1,6 @@ +1. Copy the following artefacts to a folder on the server: + * Cortex Innovation 2024.5 - Block Packages.zip + * Cortex Innovation 2024.5 - App Services.zip + * Cortex Innovation 2024.5 - App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.5 - App Server Install Scripts.zip` file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/run-upgrade-script.md new file mode 100644 index 000000000..b1eb1a11c --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/single-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.5 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the application services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/upgrade-flows.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/upgrade-flows.md new file mode 100644 index 000000000..1168d5d98 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-application-server/upgrade-flows.md @@ -0,0 +1,28 @@ +On the Web Application Server, copy the `Cortex Innovation 2024.5 - Flows Upgrader.zip` artefacts to a folder on it: +1. Extract the `Cortex Innovation 2024.5 - Flows Upgrader.zip` file to a folder with the same name. +1. Open a Windows PowerShell (x64) window as administrator. The administrator must be a domain user that is a member of the local Administrators group on the Web Application Server. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.5 - Flows Upgrader` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.5 - Flows Upgrader" + ``` + +1. Export the flows to be upgraded from Gateway as a studio package. +1. Run the `Cortex.Upgrade.FlowUpgrader.exe` application using the following command, modifying the argument value to contain the extracted studio package of flows to upgrade: + + ```powershell + .\Cortex.Upgrade.FlowUpgrader.exe "C:\Install\Export.studiopkg" + ``` + +1. A message similar to the following will indicate that the application has completed successfully: + + ```text + Upgrading Flows + Flow Upgraded: Test Flows\TestFlow1.flow + Flow Upgraded: Test Flows\TestFlow3.flow + Flow Upgraded: Test Flows\TestFlow2.flow + Flows Upgraded + Upgraded Studio Package Created: export-28UpgradedTo30.StudioPkg + ``` + +1. A new studio package will be created in the same file path as the package given as the argument with the format `{PackageName}-{PreviousVersion}UpgradedTo{NewVersion}.studiopkg`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/configure-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/configure-gateway-script.md new file mode 100644 index 000000000..84057e4a7 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/configure-gateway-script.md @@ -0,0 +1,35 @@ +1. In the `Cortex Innovation 2024.5 - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.5 - Gateway.zip" ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation 2024.5 - Gateway.zip` file on the server. | + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false`.| + |`CertificateFriendlyName` | Replace this with the friendly name that is allocated to the certificate that {{% ctx %}} Gateway is currently using.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this to `$false` if you do not require the latest recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this to `$false` if you are not using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +[Security Best Practices]: {{< url path="Cortex.Guides.UpgradeCortex.Advanced.SSLBestPractices" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/run-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/run-gateway-script.md new file mode 100644 index 000000000..c627e6c97 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/run-gateway-script.md @@ -0,0 +1,32 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.5 - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.5 - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the upgrade. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/test-upgrade.md b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/test-upgrade.md new file mode 100644 index 000000000..e56d291ae --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.5/upgrade-web-application-server/test-upgrade.md @@ -0,0 +1,28 @@ +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Flows` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Flow` 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][] 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, if those blocks are not displayed see [Troubleshooting][]. A list of block palettes should be displayed down the left hand side: + {{< figure src="../../2024.5/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. Failing that, see [Troubleshooting][]. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Settings` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. See [Troubleshooting][] for more information. + +[Troubleshooting]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/multi-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/multi-server/run-upgrade-script.md new file mode 100644 index 000000000..25682b1aa --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/multi-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the HA Services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/configure-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/configure-upgrade-script.md new file mode 100644 index 000000000..eb9ce06d7 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/configure-upgrade-script.md @@ -0,0 +1,37 @@ +1. In the `Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.ApplicationConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or the values should be changed then use the `Use New Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.7 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.7 - Block Packages.zip" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.7 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.7 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-app-upgrade-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..4f2b7dd33 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/make-installation-artefacts-available.md @@ -0,0 +1,6 @@ +1. Copy the following artefacts to a folder on the server: + * Cortex Innovation 2024.7 - Block Packages.zip + * Cortex Innovation 2024.7 - App Services.zip + * Cortex Innovation 2024.7 - App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.7 - App Server Install Scripts.zip` file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/run-upgrade-script.md new file mode 100644 index 000000000..465b4b14a --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-application-server/single-server/run-upgrade-script.md @@ -0,0 +1,29 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.7 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the application services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/configure-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/configure-gateway-script.md new file mode 100644 index 000000000..05cfdc5c2 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/configure-gateway-script.md @@ -0,0 +1,48 @@ +1. In the `Cortex Innovation 2024.7 - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.GatewayConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or any of the values should be changed then use the `Use New Configuration Values` tab removing any of the parameters that do need need to change leaving the minimum required parameters as can be seen in the `Use Previous Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.7 - Gateway.zip" ` + -ApplySecurityMeasures $true ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.7 - Gateway.zip" ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation 2024.7 - Gateway.zip` file on the server. | + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false`.| + |`CertificateFriendlyName` | Replace this with the friendly name that is allocated to the certificate that {{% ctx %}} Gateway is currently using.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this to `$false` if you do not require the latest recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this to `$false` if you are not using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +[Security Best Practices]: {{< url path="Cortex.Guides.UpgradeCortex.Advanced.SSLBestPractices" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/run-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/run-gateway-script.md new file mode 100644 index 000000000..dc5cea551 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/run-gateway-script.md @@ -0,0 +1,32 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.7 - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.7 - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the upgrade. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/test-upgrade.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/test-upgrade.md new file mode 100644 index 000000000..64a654d58 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/test-upgrade.md @@ -0,0 +1,28 @@ +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Flows` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Flow` 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][] 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, if those blocks are not displayed see [Troubleshooting][]. A list of block palettes should be displayed down the left hand side: + {{< figure src="../../2024.7/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. Failing that, see [Troubleshooting][]. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Settings` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. See [Troubleshooting][] for more information. + +[Troubleshooting]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md new file mode 100644 index 000000000..503ea92b1 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.7/upgrade-web-application-server/upgrade-flows.md @@ -0,0 +1,43 @@ +1. Export the flows to be upgraded from {{% ctx %}} Gateway as a studio package: + 1. In a browser, navigate to {{% ctx %}} Gateway and log in as a user with administrative privileges. + 1. Click on the `Settings` charm and select `Studio Export`. + 1. Select all the flows to be upgraded and click `Export`. + 1. A message should be displayed confirming that the studio package was exported successfully. +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.7 - Flows Upgrader` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.7 - Flows Upgrader" + ``` + +1. Run the `Cortex.Upgrade.FlowsUpgrader.exe` application using the following command, modifying the path specified to contain the extracted studio package of flows to upgrade (typically this will have been exported to the local `Downloads` folder): + + ```powershell + .\Cortex.Upgrade.FlowsUpgrader.exe "C:\Users\{Username}\Downloads\export.studiopkg" + ``` + +1. A message similar to the following will indicate that the application has completed successfully: + + ```text + Upgrading Flows + Flow Upgraded: Test Flows\TestFlow1.flow + Flow Upgraded: Test Flows\TestFlow3.flow + Flow Upgraded: Test Flows\TestFlow2.flow + Flows Upgraded + Upgraded Studio Package Created: export-28UpgradedTo30.StudioPkg + ``` + + A new studio package will have been created in the same location as the original export package with the name `{PackageName}-{PreviousVersion}UpgradedTo{NewVersion}.studiopkg`. +1. Import the upgraded flow package into {{% ctx %}} Gateway: + 1. In a browser, navigate to {{% ctx %}} Gateway and log in as a user with administrative privileges. + 1. Click on the `Settings` charm and select `Studio Import`. + 1. Select `Browse` and locate and select the upgraded studio package and click `Open`. + 1. Verify that there are no flows with a red status and click `Import`. + 1. A message should be displayed confirming that the studio package was imported successfully. +1. Re-publish any previously published packages: + 1. Click on the `Settings` charm and select `Packages`. + 1. On the table of Package Definitions filter the Is Published column to display `Is Published`. + 1. For each package listed select it in the table then: + 1. Scroll down to below the package definition and select `Create New Version`. + 1. Click `Save`. + 1. Click `Publish`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/multi-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/multi-server/run-upgrade-script.md new file mode 100644 index 000000000..1e4d54d40 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/multi-server/run-upgrade-script.md @@ -0,0 +1,30 @@ +1. Open a Windows PowerShell (x64) window as administrator. + {{< alert title="Important" color="warning" >}}It is critical to make sure this is a new PowerShell window. If any Service Fabric cmdlets have been run previously to running the `Cortex.Innovation.Upgrade.ps1` script, the upgrade will close halfway through due to the PowerShell module being updated.{{< /alert >}} +1. Navigate PowerShell to inside the `Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the HA Services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/configure-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/configure-upgrade-script.md new file mode 100644 index 000000000..c52a96eff --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/configure-upgrade-script.md @@ -0,0 +1,37 @@ +1. In the `Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server` folder, locate the `Cortex.Innovation.Upgrade.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.ApplicationConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or the values should be changed then use the `Use New Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.9 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.9 - Block Packages.zip" ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-ha-upgrade-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Upgrade.ps1 ` + -AppServicesPath "C:\Install\Cortex Innovation 2024.9 - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation 2024.9 - Block Packages.zip" ` + -ApplicationServerIPv4Addresses @("192.168.1.1") ` + -Credential $Credential ` + -AcceptEULA:$AcceptEULA ` + *>&1 | Tee-Object -FilePath "cortex-app-upgrade-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the server. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the server. | + |`ApplicationServerIPv4Addresses` | The IPv4 address of the server.| + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that upgrade logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Upgrade.ps1`. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/make-installation-artefacts-available.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/make-installation-artefacts-available.md new file mode 100644 index 000000000..ada75ad8f --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/make-installation-artefacts-available.md @@ -0,0 +1,6 @@ +1. Copy the following artefacts to a folder on the server: + * Cortex Innovation 2024.9 - Block Packages.zip + * Cortex Innovation 2024.9 - App Services.zip + * Cortex Innovation 2024.9 - App Server Install Scripts.zip + +1. Extract the `Cortex Innovation 2024.9 - App Server Install Scripts.zip` file to a folder with the same name. diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/run-upgrade-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/run-upgrade-script.md new file mode 100644 index 000000000..d1342b54c --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-application-server/single-server/run-upgrade-script.md @@ -0,0 +1,30 @@ +1. Open a Windows PowerShell (x64) window as administrator. + {{< alert title="Important" color="warning" >}}It is critical to make sure this is a new PowerShell window. If any Service Fabric cmdlets have been run previously to running the `Cortex.Innovation.Upgrade.ps1` script, the upgrade will close halfway through due to the PowerShell module being updated.{{< /alert >}} +1. Navigate PowerShell to inside the `Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.9 - App Server Install Scripts\Upgrade Application Server" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Upgrade.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade the application services and required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Upgrade][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Troubleshooting During Upgrade]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/configure-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/configure-gateway-script.md new file mode 100644 index 000000000..948c17a79 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/configure-gateway-script.md @@ -0,0 +1,48 @@ +1. In the `Cortex Innovation 2024.9 - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this upgrade, then update the script to match, changing the parameters according to the details given below: + + {{% alert title="Note" %}} +To check the previous configuration values open the `Cortex.Upgrade.GatewayConfig.json` file located in `%ProgramData%\Cortex\Upgrade`. If the file does not exist or any of the values should be changed then use the `Use New Configuration Values` tab removing any of the parameters that do need need to change leaving the minimum required parameters as can be seen in the `Use Previous Configuration Values` tab. + {{% /alert %}} + + {{< tabpane lang="powershell" >}} + {{< tab header="Use Previous Configuration Values" >}} +.\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.9 - Gateway.zip" ` + -ApplySecurityMeasures $true ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + {{< /tab >}} + {{< tab header="Use New Configuration Values">}} +.\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation 2024.9 - Gateway.zip" ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation 2024.9 - Gateway.zip` file on the server. | + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false`.| + |`CertificateFriendlyName` | Replace this with the friendly name that is allocated to the certificate that {{% ctx %}} Gateway is currently using.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this to `$false` if you do not require the latest recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this to `$false` if you are not using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +[Security Best Practices]: {{< url path="Cortex.Guides.UpgradeCortex.Advanced.SSLBestPractices" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/run-gateway-script.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/run-gateway-script.md new file mode 100644 index 000000000..d30893b60 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/run-gateway-script.md @@ -0,0 +1,32 @@ +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation 2024.9 - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation 2024.9 - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the upgrade. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/test-upgrade.md b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/test-upgrade.md new file mode 100644 index 000000000..79820bad5 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/2024.9/upgrade-web-application-server/test-upgrade.md @@ -0,0 +1,31 @@ +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Dev` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Activity` 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][] 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, if those blocks are not displayed see [Troubleshooting][]. A list of block palettes should be displayed down the left hand side: + {{< figure src="../../2024.9/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 Flow` and `End Flow` 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 Variables Grid, set `Is Output Variable?` to `true` for the new `Result` variable. +1. Add a breakpoint to the `End Flow` block and start the flow. An execution token should appear. + If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][]. +1. Select the execution in the Executions Grid (bottom panel). +1. The `Result` variable displayed in the Variables Viewer (right panel) should show the current time. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that there is a problem with the configuration in the `web.config` file for {{% ctx %}} Gateway, or the Application Services aren't healthy. See [Troubleshooting][] for more information. + +[Troubleshooting]: {{< url path="Cortex.Reference.Troubleshooting.Upgrade.TroubleshootingDuringUpgrade" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/try-it-out/multi-server/test-executing-production-flows.md b/content/en/docs/2024.9/_shared/upgrade/try-it-out/multi-server/test-executing-production-flows.md new file mode 100644 index 000000000..743f7e6d8 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/try-it-out/multi-server/test-executing-production-flows.md @@ -0,0 +1,15 @@ +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +1. {{% ctx %}} has now been verified and is ready to use. diff --git a/content/en/docs/2024.9/_shared/upgrade/try-it-out/single-server/test-executing-production-flows.md b/content/en/docs/2024.9/_shared/upgrade/try-it-out/single-server/test-executing-production-flows.md new file mode 100644 index 000000000..9a71ecaca --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/try-it-out/single-server/test-executing-production-flows.md @@ -0,0 +1,15 @@ +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the server you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +1. {{% ctx %}} has now been verified and is ready to use. diff --git a/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/multi-server/check-application-services.md b/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/multi-server/check-application-services.md new file mode 100644 index 000000000..b91e3adcd --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/multi-server/check-application-services.md @@ -0,0 +1,43 @@ +1. Log on to one of the Application Servers. +1. Import the client certificate used for the original installation of the application. Its location is specified in the `ClientCertificatePath` parameter of the `Cortex.Innovation.Install.ps1` file of the original installation. + + If the .PFX file is available on the server: + * Double-click on the client certificate .PFX file and follow the wizard. + + If the .PFX file is not available: + * Identify the certificate to export by opening the `Cortex.Upgrade.ApplicationConfig.json` configuration file located in `C:\ProgramData\Cortex\Upgrade` and locate the value of the `applicationServerCertificateSubject` and `applicationServerCertificateThumbprint`. + * Find the certificate by using the `Manage Computer Certificates` tool in Windows. In the `Personal` store, the certificate will have an `Issued To` similar to `applicationServerCertificateSubject` and to confirm it is the right certificate double-click the certificate, select the `Details` tab and locate the `Thumbprint` property to compare the value to that in `applicationServerCertificateThumbprint`. + * Export the certificate as a pfx file and then import it to the `Current User` store by double-clicking on it and following the wizard. +1. Open a web browser. +1. Navigate to `https://app-server.domain.com:9080/Explorer`, where `app-server.domain.com` is the fully qualified domain name of any Application Server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration of the original installation. + + The screen should resemble that in the following figure: + {{< figure src="/images/Service Fabric Explorer.png" >}} + + The status circles should be entirely green - this indicates that all nodes, services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system. + + After expanding the application, clicking on any of the services should display a green circle and `Status = Active`: + + {{< figure src="/images/Service Fabric Explorer - Service.png" >}} + + After expanding either of the services, clicking on any of the instances/partitions should display a green circle and `Status = Ready`: + + {{< figure src="/images/Service Fabric Explorer - Instance.png" >}} + + Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and `Status = Up`: + + {{< figure src="/images/Service Fabric Explorer - Node.png" >}} + + If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section. + + If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong. + + If no useful message can be seen here, the service log files may contain more information. These can be found on each Application Server at: + + * `%ProgramData%/Cortex/API Gateway Service/Logs` + * `%ProgramData%/Cortex/Execution Service/Logs` + + If no solution can be found, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +[Configure Installation Script]: {{< ref "#configure-installation-script" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} diff --git a/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/single-server/check-application-services.md b/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/single-server/check-application-services.md new file mode 100644 index 000000000..287bb3909 --- /dev/null +++ b/content/en/docs/2024.9/_shared/upgrade/upgrade-application-server/single-server/check-application-services.md @@ -0,0 +1,43 @@ +1. Log on to the server. +1. Import the client certificate used for the original installation of the application. Its location is specified in the `ClientCertificatePath` parameter of the `Cortex.Innovation.Install.ps1` file of the original installation. + + If the .PFX file is available on the server: + * Double-click on the client certificate .PFX file and follow the wizard. + + If the .PFX file is not available: + * Identify the certificate to export by opening the `Cortex.Upgrade.ApplicationConfig.json` configuration file located in `C:\ProgramData\Cortex\Upgrade` and locate the value of the `applicationServerCertificateSubject` and `applicationServerCertificateThumbprint`. + * Find the certificate by using the `Manage Computer Certificates` tool in Windows. In the `Personal` store, the certificate will have an `Issued To` similar to `applicationServerCertificateSubject` and to confirm it is the right certificate double-click the certificate, select the `Details` tab and locate the `Thumbprint` property to compare the value to that in `applicationServerCertificateThumbprint`. + * Export the certificate as a pfx file and then import it to the `Current User` store by double-clicking on it and following the wizard. +1. Open a web browser. +1. Navigate to `https://server.domain.com:9080/Explorer`, where `server.domain.com` is the fully qualified domain name of the server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration of the original installation. + + The screen should resemble that in the following figure: + {{< figure src="/images/Service Fabric Explorer - Single.png" >}} + + The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system. + + After expanding the application, clicking on any of the services should display a green circle and `Status = Active`: + + {{< figure src="/images/Service Fabric Explorer - Service - Single.png" >}} + + After expanding either of the services, clicking on any of the instances/partitions should display a green circle and `Status = Ready`: + + {{< figure src="/images/Service Fabric Explorer - Instance - Single.png" >}} + + Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and `Status = Up`: + + {{< figure src="/images/Service Fabric Explorer - Node - Single.png" >}} + + If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section. + + If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong. + + If no useful message can be seen here, the service log files may contain more information. These can be found on the server at: + + * `%ProgramData%/Cortex/API Gateway Service/Logs` + * `%ProgramData%/Cortex/Execution Service/Logs` + + If no solution can be found, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +[Configure Installation Script]: {{< ref "#configure-installation-script" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/_index.md b/content/en/docs/2024.9/getting-started/_index.md new file mode 100644 index 000000000..8f09b4077 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/_index.md @@ -0,0 +1,6 @@ +--- +title: "Getting Started" +linkTitle: "Getting Started" +description: "Get up and running with the {{% ctx %}} Innovation platform in minutes." +weight: 3 +--- diff --git a/content/en/docs/2024.9/getting-started/cloud/_index.md b/content/en/docs/2024.9/getting-started/cloud/_index.md new file mode 100644 index 000000000..2dd8742d9 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/_index.md @@ -0,0 +1,5 @@ +--- +title: "Set up in the Cloud" +linkTitle: "Set up in the Cloud" +description: "Information about setting up observability in the cloud for a {{% ctx %}} Innovation platform." +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/_index.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/_index.md new file mode 100644 index 000000000..e1be36f75 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/_index.md @@ -0,0 +1,10 @@ +--- +title: "Grafana Cloud" +linkTitle: "Grafana Cloud" +description: "Information about adding Grafana Cloud to Innovation, including details about components, supported architectures, prerequisites, installation and configuration instructions." +weight: 10 +--- + +{{% pageinfo %}} +For instructions on how to set up Grafana and Grafana Loki on-premise see {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.MainDoc" title="Grafana on-premise" >}}. +{{% /pageinfo %}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/architecture.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/architecture.md new file mode 100644 index 000000000..defbacd0e --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/architecture.md @@ -0,0 +1,32 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended architecture for a Grafana Cloud installation." +weight: 10 +--- + +# {{% param title %}} + +## Components + +| Component | Purpose | Required/Optional |Server Role | +|-----------|---------|----------|------------| +| [Grafana][] | Web application that provides querying and visualisation of data in the form of dashboards. | Required | Grafana Cloud managed service | +| [Grafana Loki][Grafana Loki] | Log aggregation system designed to store and query logs from applications and infrastructure. | Required | Grafana Cloud managed service | +| [Promtail][] | An agent which ships the contents of local logs to a Grafana Loki instance. It should be deployed to every machine that has a Microsoft Service Fabric node used by Innovation. | Required | Application Server | + +## Recommended Architecture + +The following architecture requires 1..n Application servers and 1 [Grafana Cloud][] managed service. + +{{< figure src="/images/editable/Grafana Platform Architecture Diagram - Cloud.png" >}} + +## Next Steps? + +1. [Prerequisites][] + +[Prerequisites]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Prerequisites.MainDoc" >}} +[Grafana]: {{< url path="Grafana.Products.Grafana.MainDoc" >}} +[Grafana Cloud]: {{< url path="Grafana.MainDoc" >}} +[Grafana Loki]: {{< url path="Grafana.Products.Loki.MainDoc" >}} +[Promtail]: {{< url path="Grafana.Products.Loki.Promtail.MainDoc" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md new file mode 100644 index 000000000..89bbb133e --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md @@ -0,0 +1,71 @@ +--- +title: "Import Dashboards" +linkTitle: "Import Dashboards" +description: "Information about setting up Grafana to communicate with the Cloud Grafana Loki as well as importing and configuring the default set of dashboards." +weight: 60 +--- + +# {{% param title %}} + +This guide describes where to get the default {{% ctx %}} Innovation Dashboards from and how to import them for use in Grafana Cloud. + +Please ensure that the set up for [Grafana][] and [Loki][] have been completed before starting this section. + +## Download the {{% ctx %}} Innovation Default Dashboards + +1. Download [Grafana.Dashboards.zip] archive containing the {{% ctx %}} Innovation default dashboards. +1. Extract the content of the downloaded archive to a suitable location. + +## Create Folder for Dashboards + +1. Log in to Grafana Cloud with a user that has the *Admin* role. +1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. +1. Click the Dashboards menu item. +1. Click the *New* dropdown and select *New folder*. +1. Enter a folder name, e.g. `Cortex`. +1. Click *Create*. + +## Import Dashboards + +1. Log in to Grafana Cloud with a user that has the *Admin* role. +1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. +1. Click the Dashboards menu item. +1. Click the *New* dropdown and select *Import*. +1. Click on *Upload dashboard JSON file*. +1. Locate the `Flow Execution Requests.json` file extracted from the downloaded `Grafana.Dashboards.zip`. +1. Select the file and click *Open*. +1. Select the folder in Grafana you wish the dashboard to be saved in, e.g. *Cortex*. +1. Select your [configured Loki data source][] from the dropdown menu, e.g. *grafanacloud-cortexinnovation-logs*. +1. Click *Import*. +1. Repeat steps 2 - 10 for the `Platform Health.json` file. + +## Configure Data Sources + +It is necessary to update the Custom Filter inside the dashboards to use the correct data source. + +To do this, follow these steps for all default {{% ctx %}} Innovation dashboards imported: + +1. Log in to Grafana Cloud with a user that has the *Admin* role. +1. To open a dashboard: + 1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. + 1. Click the Dashboards menu item. + 1. Click the folder name that the dashboards were imported to. + 1. Click the first dashboard to open. +1. Open the *Dashboard settings* menu via the cog icon in the top right-hand side of the dashboard. +1. Click *Variables* from the top menu of the *Settings* page. +1. Click *CustomFilter* in the *Variables* list. +1. Select your [configured Loki data source][] in the *Adhoc Options* > *Data source* drop-down menu, e.g. *grafanacloud-cortexinnovation-logs*. +1. Click *Apply*. +1. Click the dashboard name in the breadcrumb at the top left corner of the page to go back to the dashboard. +1. Click the + icon next to the Custom Filter to confirm that a list of available filter options is visible. If Grafana Loki has not received any logs from Promtail there will be no options available for selection. +1. Repeat steps 2 - 9 for all additional default dashboards. + +## Next Steps? + +1. [Try it Out][] + +[configured Loki data source]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}} +[Grafana]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.MainDoc" >}} +[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaDashboardsZip" >}} +[Loki]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}} +[Try it Out]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.TryItOut.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/_index.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/_index.md new file mode 100644 index 000000000..6f53df537 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/_index.md @@ -0,0 +1,6 @@ +--- +title: "Install Promtail" +linkTitle: "Install Promtail" +description: "Information about installing and configuring Promtail on the Application Server(s)." +weight: 50 +--- diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md new file mode 100644 index 000000000..4546b0a10 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md @@ -0,0 +1,51 @@ +--- +title: "Configure Promtail" +linkTitle: "Configure Promtail" +description: "Information about configuring Promtail on the Application Server(s)." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to configure Promtail on the Application Server(s). + +{{% alert type="note" title="Note" %}}These steps must be performed for every Promtail installation in the cluster.{{% /alert %}} + +## Configure Promtail + +### Set Client URL for Grafana Loki + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Replace the Grafana Loki `URL` template in the `clients` section with the `url` value noted down during [Set Up Grafana Loki][] steps. + A correct URL should be similar to `https://239948:eyJrIjoiaWVjNzE4MmVjOThkNTgxMMQ5MzIyZjdlMjAyYWY4NWJjO1I1OTc4NSIsIm4iOiJUZXN0S2V5IiwiaWQiOjY4Nzk0MX0=@logs-prod-008.grafana.net/api/prom/push`. +1. Save the file. + +### Set the positions.yaml File Path + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Set the `filename` in the `positions` section to the location where you want the `positions.yaml` file to be created on Promtail startup, e.g. `C:/Program Data/Cortex/Observability/Promtail/Positions.yaml`. +1. Create all the folders of the path specified in the previous step. +1. Save the file. + +{{% alert title="Note" %}} +If the specified path to the folder for the `positions.yaml` file doesn't exists, the file will not get created on Promtail startup. +{{% /alert %}} + +### Set the Path to the API Gateway Service Log Files + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Set the `__path__` in the `static_configs` > `targets` > `labels` section to the path of the `Logs` folder specified in the `appSettings.json` file during installation of the API Gateway Service, e.g. `"C:/ProgramData/Cortex/API Gateway Service/Logs/*.json"`. +1. Save the file. + +### Start Promtail + +1. Run Windows PowerShell as Administrator. +1. Change the location to the folder where the `promtail-windows-amd64.exe` file is located. +1. Execute the `.\Start-Promtail.ps1` command to start the Promtail Windows service. + +## Next Steps? + +1. [Import Dashboards][] + +[Import Dashboards]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.ImportDashboards.MainDoc" >}} +[Set Up Grafana Loki]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.SetUpGrafanaLoki" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md new file mode 100644 index 000000000..c40dde7a5 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md @@ -0,0 +1,30 @@ +--- +title: "Install Promtail" +linkTitle: "Install Promtail" +description: "Information about installing Promtail on the Application Server(s)." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to install Promtail on the Application Server(s). Please ensure that the [Prerequisites][] have been completed before starting this installation. + +## Install Promtail + +1. Download [Promtail 3.0.0][] archive. +1. Extract content of the downloaded archive to a suitable location, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. Download the [Promtail Install.zip][] archive and extract its contents alongside the previously extracted Promtail `promtail-windows-amd64.exe`. +This archive contains the `promtail-local-config.yaml` configuration file, [NSSM][] (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Promtail as a Windows service. +1. Run Windows PowerShell as Administrator +1. Change the location to where all the files were extracted to in step 2, e.g. `cd "C:\Program Data\Cortex\Observability\Promtail"`. +1. Execute the `.\Install-Promtail.ps1` command to install the downloaded `promtail-windows-amd64.exe` as a service. + +## Next Steps? + +1. [Configure Promtail][] + +[Configure Promtail]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.InstallPromtail.ConfigurePromtail.MainDoc" >}} +[NSSM]: {{< url path="NSSM.MainDoc" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Prerequisites.MainDoc" >}} +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[Promtail Install.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/prerequisites.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/prerequisites.md new file mode 100644 index 000000000..9f5965e90 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/prerequisites.md @@ -0,0 +1,59 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- +# {{% param title %}} + +The prerequisites required for each server role (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking the installation. + +## Hardware Requirements + +The application servers (as described in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.Architecture" title="Architecture" >}}) to which Promtail will be added have already been installed as part of the Innovation install process and do not require any hardware modifications for the observability platform installation. + +{{% alert title="Note" %}} +The application servers must have internet access in order to communicate with the Grafana Cloud managed service. +{{% /alert %}} + + +## Software Requirements + +| Server Role | Windows Server[^1] | Other Software | +|--------------------|------------------------------------------------|--------------------| +| Application Server | [2022 (x64)][] *Recommended*
[2019 (x64)][] | [Promtail 3.0.0][] | + +[^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. + +## Web Browser Requirements + +Grafana supports the latest versions of the following browsers: + +* Chrome/Chromium +* Firefox +* Safari +* Microsoft Edge + +{{% alert title="Note" %}} +Always enable JavaScript in your browser. Running Grafana without JavaScript enabled in the browser is not supported. +{{% / alert %}} + +## Additional Application Server Requirements + +These requirements apply to each of the Application Servers. + +### Security Requirements + +#### Installation User + +A domain user which is a member of the Local Administrators group on all Application Servers must be available to perform the installation. + +## Next Steps? + +1. [Set up Grafana][] + +[2019 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2019" >}} +[2022 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2022" >}} +[Architecture]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Architecture.MainDoc" >}} +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[Set up Grafana]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.MainDoc" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-grafana.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-grafana.md new file mode 100644 index 000000000..6d3d9fe69 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-grafana.md @@ -0,0 +1,33 @@ +--- +title: "Set up Grafana" +linkTitle: "Set up Grafana" +description: "Information about setting up Grafana in the cloud." +weight: 30 +--- + +# {{% param title %}} + +## Sign up for Grafana Cloud + +1. Browse to [Grafana Labs][]. +1. Find and click the link to create free account. +1. Create your account and follow any account verification steps. +1. If asked to start a free trial, do so. +1. On the **Let's create your Grafana Stack** dialog: + + {{< figure src="/images/Grafana Cloud - Create Stack.png" >}} + + * Enter an appropriate `Team URL` which will be used as a customised link to access the Grafana Cloud. + * Select the `Deployment region` which is where the service will be deployed to. This should be preferably close to the High Availability nodes. + * Review the terms and conditions as well as any agreements. + * Click `Finish Setup`. + +1. Wait for Grafana Cloud to load + +## Next Steps? + +1. [Set up Grafana Loki][] + + +[Grafana Labs]: {{< url path="Grafana.MainDoc" >}} +[Set up Grafana Loki]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-loki.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-loki.md new file mode 100644 index 000000000..d8495b8b6 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/setup-loki.md @@ -0,0 +1,33 @@ +--- +title: "Set up Grafana Loki" +linkTitle: "Set up Grafana Loki" +description: "Information about setting up Grafana Loki in the cloud." +weight: 40 +--- + +# {{% param title %}} + +This guide describes how to set up Grafana Loki in the cloud. Please ensure that the [Prerequisites][] have been completed before starting this installation. + +## Set up Grafana Loki + +1. Browse to the *Team URL* created during [Sign Up For Grafana Cloud][]. +1. If presented with the *Get started in a few easy steps* page, click *I'm already familiar with Grafana. Skip setup →* in the top right corner. +1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. +1. Click the *Connections* menu item and select *Add new connection*. +1. In the *Custom data* section click on *Hosted logs*. +1. In the *Choose your use case* section select *Send logs from a standalone host*. + {{< figure src="/images/Grafana Cloud - Hosted Logs Config Usecase.png" >}} +1. Enter an *API Token name* in the *Configure promtail to send logs to your Grafana Cloud* section and click the *Create API token* button. +The token name is used in the Grafana Cloud website to easily identify the key after its creation. + {{< figure src="/images/Grafana Cloud - Hosted Logs Config Token Name.png" >}} +1. Make a note of the value of the *url* in the *client* section of the example configuration. Ignore the instruction to copy and paste the whole content. + {{< figure src="/images/Grafana Cloud - Hosted Logs Config Data.png" >}} + +## Next Steps? + +1. [Install Promtail][] + +[Install Promtail]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.InstallPromtail.MainDoc" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Prerequisites.MainDoc" >}} +[Sign Up For Grafana Cloud]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.SignUpForGrafanaCloud" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/try-it-out.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/try-it-out.md new file mode 100644 index 000000000..a64a07976 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/Grafana/try-it-out.md @@ -0,0 +1,49 @@ +--- +title: "Try it Out" +linkTitle: "Try it Out" +description: "Information about trying out Grafana Observability Dashboards for the first time." +weight: 60 +--- + +# {{% param title %}} + +## Check Dashboards are Displaying Data + +{{% alert title="Note" %}} +This test uses the test flow published as part of testing the Innovation installation. See {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.TryItOutPublishedFlow" title="Testing HA installation" >}} or {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.TryItOutPublishedFlow" title="Testing non-HA installation" >}}. An alternative flow can be used that exists on the system and can be executed. +{{% / alert %}} + +1. Open an HTTP client, such as [Postman][]. Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | For HA installation use:
`https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`
e.g. `https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage`

For non-HA installation use:
`https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`
e.g. `https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage`| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services. See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.| + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted). See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.| + + {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you may need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. Once the request has completed, using a web browser, log in to your configured Grafana. +1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. +1. Click the Dashboards menu item. +1. Click the folder name that the dashboards were imported to, if not already expanded. +1. Click the *Flow Execution Requests* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} +1. Click the Menu icon {{< image src="/images/GrafanaMenuIcon.png" title="Menu icon" >}} to view the available options. +1. Click the Dashboards menu item. +1. Click the folder name that the dashboards were imported to, if not already expanded. +1. Click the *Platform Health* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} + +[Postman]: {{< url path="Postman.Downloads.MainDoc" >}} +[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScript" >}} +[Non-HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScript" >}} diff --git a/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/_index.md b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/_index.md new file mode 100644 index 000000000..4c94478e8 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/cloud/add-observability-to-innovation/_index.md @@ -0,0 +1,6 @@ +--- +title: "Add Observability to Innovation" +linkTitle: "Add Observability to Innovation" +description: "Information about setting up an observability platform for Innovation." +weight: 30 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/_index.md b/content/en/docs/2024.9/getting-started/on-premise/_index.md new file mode 100644 index 000000000..27a11df92 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/_index.md @@ -0,0 +1,9 @@ +--- +title: "Install On-Premise" +linkTitle: "Install On-Premise" +description: "Information about installing {{% ctx %}} Innovation to virtual machines or physical servers on-premise." +--- + +{{% pageinfo %}} +{{% ctx %}} Innovation can be deployed on-premise [on its own](install-innovation-only) or added to an [existing](add-innovation-to-72) 7.2 installation. +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/_index.md new file mode 100644 index 000000000..19d0dbf9d --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/_index.md @@ -0,0 +1,10 @@ +--- +title: "Add Innovation to a 7.2 Installation" +linkTitle: "Add Innovation to a 7.2 Installation" +description: "Information about adding {{% ctx %}} Innovation to an existing {{% ctx %}} 7.2 platform." +weight: 20 +--- + +{{% pageinfo %}} +{{% ctx %}} Innovation can be deployed on-premise across [multiple servers](multiple-server-with-ha) to provide improved scale and high availability (HA), or to a [single server](single-server-without-ha) if scale and HA aren't required. +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..b37f4309c --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/_index.md @@ -0,0 +1,12 @@ +--- +title: "Multiple Server - With HA (Recommended)" +linkTitle: "Multiple Server - With HA" +description: "Information about adding {{% ctx %}} Innovation to {{% ctx %}} 7.2 across multiple on-premise servers with high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions." +weight: 10 +--- + +{{% pageinfo %}} +Multiple server installations with HA are recommended for the following scenarios: + +* Production installations that are required to scale and support HA +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/architecture.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/architecture.md new file mode 100644 index 000000000..8f5e24f2e --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/architecture.md @@ -0,0 +1,41 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended platform architecture, including component descriptions." +weight: 10 +--- + +# {{< param title >}} + +## Components + +{{< section "/architecture/components/multi-server.md" >}} + +{{% alert title="Note" %}} +{{% ctx %}} v7.2 component descriptions are not covered in this guide. See separate v7.2 documentation for more information. +{{% /alert %}} + +## Possible Architectures + +{{% ctx %}} Innovation and v7.2 can run side-by-side, allowing flows to be built and run for both of them from the same Gateway instance. They each require a different set of back-end components to be installed. Innovation can be added to a v7.2 installation and the only component shared by both Innovation and v7.2 is {{% ctx %}} Gateway. + +### Recommended Architecture + +The recommended architecture for adding Innovation to a v7.2 Dual Site, Dual Server system requires 8 servers in total; the 4 existing servers, plus 4 new servers: + +* 2x Existing Application Servers for v7.2, one of these will also act as the Web Application Server for Innovation. For Innovation, the existing Gateway will be upgraded and a new Debug Node will be added +* 2x Existing Database Servers, used for v7.2 +* 1x New Load Balancer Server for Innovation +* 3x New Application Servers for Innovation + +{{< figure src="/images/editable/Cortex Innovation and v7.2 Best Architecture.png" class="centre" title="8 Server, Recommended Architecture Diagram" >}} + +{{< section "/architecture/components/node-details.md" >}} + +## Next Steps? + +1. [Prerequisites][] + +[Hardware Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.HardwareRequirements" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.Prerequisites" >}} +[Recommended]: {{< ref "#recommended-architecture" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..95a70cf70 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-application-and-loadbalancer-servers.md @@ -0,0 +1,335 @@ +--- +title: "Install Application Servers and Load Balancer" +linkTitle: "Install Application Servers and Load Balancer" +description: "Information about installing the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to install the Application Servers and Load Balancer Server. Please ensure that [Prerequisites for adding Innovation to v7.2][] have been read before starting this installation. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used for installation, and copy the following artefacts to a folder on it: + * Cortex Innovation {{< version >}} - App Server Install Scripts.zip + * Cortex Innovation {{< version >}} - App Services.zip + * Cortex Innovation {{< version >}} - Block Packages.zip + +1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name. + +## Install Microsoft .NET Framework 4.7.2 + +Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.2 to be installed on each Application Server. + +To find the version of the framework that is installed: + +1. On the Start menu, choose `Run`. +1. In the open box, enter `regedit.exe`. You must have administrative credentials to run regedit.exe. +1. In the Registry Editor, open the subkey `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full`. +1. If the `Full` subkey is not present, then you do not have the .NET Framework 4.5 or later installed. +1. Check for a `DWORD` value named `Release`. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is `461808` or over then at least .NET Framework 4.7.2 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it. + +To install .NET Framework 4.7.2: + +1. Download the [.NET Framework 4.7.2][NET Framework 472] installer. +1. Double-click on the installer file to run it. +1. Follow the wizard to complete the installation. + +## Apply Recommended Security Measures + +These are non-compulsory security measures, recommended to be applied to Application Servers and the Load Balancer Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. + +Applying these measures may impact other applications running on your servers. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes. + +### Only Use Recommended Encryption Algorithms and TLS Protocols + +A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at [SSL Best Practices][]. + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on {{% ctx %}} components themselves as well as their communication capabilities with third party systems and services, e.g. Execution Service executing flows with blocks which communicate with 3rd parties via PowerShell or REST. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} + +The settings can be applied by running a script. Be aware that each server will be restarted when the script is run. Apply the settings by following these instructions: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + + {{% alert title="Note" %}} +To avoid answering all of the prompts `-Override 0` can be added to the end of the script. This will automatically apply all settings and forcibly restart the servers. + {{% /alert %}} + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press `OK`. + + If `-Override 0` has been specified no further steps need to be taken and you can move on to the next section when the servers have restarted. +1. To use all the recommended settings click `Apply all` to each `Apply Cortex recommended security best practices` prompt. + + To selectively apply each setting select `Choose which to apply`. Each change will then be prompted with a Yes/No confirmation before applying. This will need to be done for each server. +1. Restart each machine when the script asks. The current machine will be restarted last, the PowerShell script will close at this time. + +## Add Antivirus Exclusions + +If Windows Defender is not running on the Application Servers, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on each of the Application Servers and continue to the next section, otherwise follow these steps: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Add.WindowsDefenderExclusions.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK. +1. A message will indicate that the script has completed successfully. + +## Check Port Usage + +To check all necessary ports are free, follow these steps: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Test.PortUsage.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK. + +1. If all ports are free, the script will report the following for each Application Server: + + `All ports required by Cortex Innovation are free` + + If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the `Cortex.Innovation.Install.Config.json` configuration file, in the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, to use different ports. This will be used later during installation. + + The `Cortex.Innovation.Test.PortUsage.ps1` script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free. + +## Configure Installation Script + +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs, Built-in Load Balancer">}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -ClientCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ClientCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs, Built-in Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -UseSelfSignedCertificates ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="CA Certs, Alternative Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -ClientCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ClientCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs, Alternative Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server used for installation. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server used for installation. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed [later, when upgrading Gateway][Upgrade Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed [later, when upgrading Gateway][Upgrade Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server used for installation. | + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. This is only needed if using the built-in load balancer. | + |`ServerCertificatePath` | The local path of a .PFX certificate file on the first Application Server in the `ApplicationServerIPv4Addresses` list. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the HA cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`ClientCertificatePath` | The local path of a .PFX certificate file on the first Application Server in the `ApplicationServerIPv4Addresses` list. This can be the same certificate as the `ServerCertificatePath`. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the load balancer and the nodes on the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + |`ClientCertificatePassword` | The password for the .PFX certificate file specified in `ClientCertificatePath`.

This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. Use when using an alternative load balancer or no load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed [later, when upgrading Gateway][Upgrade Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigMultipleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +## Test Installation Script + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 -WhatIf + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -WhatIf -AcceptEULA + ``` + +1. Run the PowerShell command to test the installation script. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. +1. Wait for the command to finish. It will display the output of the installation command without making any changes to the platform, to ensure things like communication between the servers are working. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them. + + If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

If this does not work, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. The `WhatIf` script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with `-WhatIf` (e.g. `Cortex.Innovation.Install.Config-WhatIf.json`). This file can be provided when obtaining support. + +## Run Installation Script + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install HA Services and the required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from [{{% ctx %}} Service Portal][CORTEX Service Portal]. Press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation. + + In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command: + + ```powershell + .\Cortex.Innovation.Uninstall.ps1 + ``` + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Installation][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +## Check Application Services + +{{< section "/install-application-server/multi-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade the Web Application Server][] + +[alternative load balancer]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.AltLoadBalancer" >}} +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.AntivirusExclusions" >}} +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.CertificateRequirements" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureInstallationScript" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.EncryptionRequirements" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Prerequisites for adding Innovation to v7.2]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.Prerequisites" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} +[Upgrade Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[Upgrade the Web Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.AddInnovationTo72WebApplicationServer" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/_index.md new file mode 100644 index 000000000..de8fd65f8 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Upgrade the Web Application Server" +linkTitle: "Upgrade Web Application Server" +description: "Information about upgrading the Web Application Server to include Innovation." +weight: 40 +--- + +This guide describes how to upgrade the v7.2 Web Application Server to Include Innovation. Please ensure that [Install Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v7.2 version of Gateway and its prerequisites have already been installed. + +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md new file mode 100644 index 000000000..dbbcf7358 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md @@ -0,0 +1,60 @@ +--- +title: "Install Flow Debugger" +linkTitle: "Install Flow Debugger" +description: "Information about installing the Flow Debugger." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to install the Flow Debugger on the Web Application Server. Please ensure that the [web application server prerequisites][] have been completed before starting this installation. + +{{% alert title="Important" color="warning" %}} +{{< ctx >}} Gateway requires a local instance of the Application Server components to enable the debugging of flows. +{{% /alert %}} + +## Install Microsoft .NET Framework 4.7.2 + +{{< section "/install-application-server/install-dot-net-framework.md">}} + +## Add Antivirus Exclusions + +If Windows Defender is not running on the server, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps: + +{{< section "/install-application-server/single-server/add-antivirus-exclusions.md">}} + +## Check Port Usage + +{{< section "/install-application-server/single-server/check-port-useage.md">}} + +## Configure Installation Script + +{{< section "/install-web-application-server/add-innovation-to-7.2/configure-debugger-installation-script.md">}} + +## Test Installation Script + +{{< section "/install-application-server/single-server/test-installation-script.md">}} + +## Run Installation Script + +{{< section "/install-application-server/single-server/run-installation-script.md">}} + +## Add Read and Execute access to Windows Crypto folder + +{{< section "/install-application-server/single-server/add-permissions-to-crypto-folder.md">}} + +## Check Application Services + +{{< section "/install-application-server/single-server/check-application-services.md">}} + +# Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade Gateway][] + +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.AntivirusExclusions" >}} +[Upgrade Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.GatewayInstallation" >}} +[web application server prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.WebApplicationServerPrerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md new file mode 100644 index 000000000..01307b5d3 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md @@ -0,0 +1,124 @@ +--- +title: "Upgrade Gateway" +linkTitle: "Upgrade Gateway" +description: "Information about upgrading v7.2 {{% ctx %}} Gateway to include Innovation." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to upgrade {{% ctx %}} Gateway on v7.2 to include Innovation. Please ensure that the [Flow Debugger installation][] has been completed before starting this installation. + +## Perform Gateway Installation + +### Configure {{% ctx %}} Gateway Installation Script + +1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` + -FeatureFlags "InnovationId" ` + -ServiceFabricApiGatewayEndpoint "https://server.domain.com/" ` + -ServiceFabricUsingSelfSignedCertificates $false ` + -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerEndpoint "https://server.domain.com:8722/api/" ` + -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` + -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFilePath "C:\Install\Certificate.pfx" ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | + |`FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} Innovation feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Licensing Requirements][], if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will set the `FeatureFlags` value in the Gateway web.config.| + |`ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Load Balancer Server. The port should be specified if it is not the default HTTPS port (443), and there must be a trailing slash, e.g. `https://server.domain.com/` or `https://server.domain.com:8722/`.

This will set the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Servers][Configure Installation Script], `$true` if you used self-signed certificates.

This will set the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`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.

This will overwrite the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Servers][Configure Installation Script]; if so, this value must be configured to the one used.

This will overwrite the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Web Application Server.

This will set the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Flow Debugger installation]; if so, this value must be configured to the one used.

This will overwrite the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Flow Debugger installation]; if so, this value must be configured to the one used.

This will overwrite the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will set the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false` if the certificate is already imported.

Note that prior to installation the certificate must be [assigned a friendly name][Assign Certificate Friendly Name]. + |`CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged.| + |`CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false` this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created Cortex site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +### Upgrade {{% ctx %}} Gateway + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/add-innovation-to-7.2/grant-gateway-user-additional-folder-permissions.md">}} + +# Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Try it out][] + +[Assign Certificate Friendly Name]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.AssignCertificateFriendlyNameNew" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.EncryptionRequirements" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureInstallationScript" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Flow Debugger installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.DebuggerInstallation" >}} +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.LicensingRequirements" >}} +[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/prerequisites.md new file mode 100644 index 000000000..86643f086 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/install-web-application-server/prerequisites.md @@ -0,0 +1,56 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +Please ensure that [Install Application Servers and Load Balancer][] has been completed before starting this installation. These steps assume that the v7.2 version of Gateway and its prerequisites have already been installed. + +## Make Installation Artefacts Available + +{{% alert title="Note" %}} +We recommend that the single-node Service Fabric instance, used by {{% ctx %}} Gateway as a Debugger instance, and {{% ctx %}} Gateway are installed on the same Web Application Server. +{{% /alert %}} + +{{< section "/install-web-application-server/make-installation-artefacts-available.md">}} + +## Licensing + +{{< section "/install-web-application-server/add-innovation-to-7.2/licensing.md">}} + +## Grant folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/grant-gateway-user-folder-permissions.md">}} + +## Certificate Requirements + +In order to ensure that the correct certificate is used during the upgrade of {{% ctx %}} Gateway, it is necessary to [assign a friendly name][Assign Certificate Friendly Name] to the certificate that is currently being used for {{% ctx %}} Gateway. It is important to set the `ImportCertificate` parameter to `$false` when [configuring the {{% ctx %}} Gateway installation script][Configure CORTEX Gateway Installation Script]. +
+The Flow Debugger also requires an X.509 SSL certificate to be installed on the Web Application Server. This can use the same certificate as {{% ctx %}} Gateway, however it must have the following properties: + +* Subject field must be in one of the following formats depending on whether a multi-domain or wildcard certificate is used: + * Multi-domain certificate - If using the [gobetween][] load balancer this should be specified as the FQDN of the load balancer server (e.g. `CN=load-balancer.domain.com`). If using a different load balancer this must be specified as the FQDN of one of the application servers (e.g. `CN=application-server.domain.com`) + * Wildcard certificate - wildcard format, pertaining to the domain of the Application Servers (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. Additionally if using a multi-domain certificate: + * The FQDN, NetBIOS Name and IP address of the web application server and all application servers must be added. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +### Assign Certificate Friendly Name + +{{< section "/install-web-application-server/add-innovation-to-7.2/assign-certificate-friendly-name.md">}} + +## Next Steps? + +1. [Install Flow Debugger][] + +[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} +[Configure CORTEX Gateway Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} +[Install Flow Debugger]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.DebuggerInstallation" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md new file mode 100644 index 000000000..dec2805bf --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md @@ -0,0 +1,354 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- + +# {{< param title >}} + +The prerequisites required for each server role (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking installation. + +{{% alert title="Note" %}} +All server roles (e.g. Load Balancer, Application Server, Web Application Server) referenced in the rest of this guide will refer to Innovation server roles unless otherwise stated. +{{% / alert %}} + +## Hardware Requirements + + +| Server Role | Servers Required | CPU Cores (> 2GHz) | RAM (GB) | Disk (GB) | +|------------------|-----------------------|-----------------------------------|---------------|----------------------| +| New Innovation Load Balancer | 1[^1] | 4+ *Recommended*
2 *Minimum* | 8+ *Recommended*
4 *Minimum* | 50+ *Recommended*
30 *Minimum*
5+ free on installation drive | +| New Innovation Application Server | 3 *Bronze availability*[^2]
5 *Silver availability*
7 *Gold availability*
9 *Platinum availability* | 4+ *Recommended*
2 *Minimum* | 16+ *Recommended*
8 *Minimum* | 75+ *Recommended*
60 *Minimum*
40+ free on %ProgramData% drive | +| Existing V7.2 Application Server with Gateway
+ Upgrade to Innovation Web Application Server | 1 | 4+ *Recommended*
4 *Minimum* | 16+ *Recommended*
12 *Minimum* | 160+ *Recommended*
135 *Minimum*
30+ free on installation drive
40+ free on %ProgramData% drive | + +[^1]: A software-based load balancer called [gobetween][] is provided with the platform. This must be installed on its own server as it doesn't support routing traffic to itself. It also doesn't currently support HA, but it may be possible to use multiple gobetween load balancers with Anycast network addressing and routing to provide high availability, as described in [https://en.wikipedia.org/wiki/Anycast][Anycast]; however, this has not been verified yet. It is possible to use an [alternative load balancer][] to the one provided. +[^2]: Application Servers support HA via clustering. A cluster must consist of a minimum of 3 nodes, and the number of nodes must be an odd number to ensure a quorum. Currently only the Bronze availability (3 nodes) is supported. Silver, Gold and Platinum support will be added in future. + +## Software Requirements + +| Server Role | Windows Server[^1] | .Net | PowerShell[^2] | IIS[^3] | Other Software | +|------------------|-------------------------|------|------------|---------|----------| +| Load Balancer | [2019 (x64)][Microsoft Server 2019] *Recommended*
[2016 (x64)][Microsoft Server 2016] | [Framework 4.7.2][NET Framework 472] | 5.1 | | +| Application Server | [2019 (x64)][Microsoft Server 2019] *Recommended*
[2016 (x64)][Microsoft Server 2016] | [Framework 4.7.2][NET Framework 472] | 5.1 | | +| Web Application Server | [2019 (x64)][Microsoft Server 2019] *Recommended*
[2016 (x64)][Microsoft Server 2016] | [Framework 4.7.2][NET Framework 472] | 5.1 | 10.0.17763[^4]
10.0.14393[^5]
[URL Rewrite Module 2.1][IIS Url Rewrite] | [Microsoft Web Deploy 3.0 or later][Web Deploy]
[Visual C++ Redistributable 2013 (x64)][C++ Redistributable] | + +[^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. +[^2]: PowerShell 5.1 ships with Windows Server 2016 and 2019. +[^3]: IIS is supported; other web servers, including IIS Express are not supported. +[^4]: Ships as a windows role within Windows Server 2019. +[^5]: Ships as a windows role within Windows Server 2016. + +## Backup Requirements + +It is important to ensure that there are relevant backups in place to be able to restore the platform in the event of a failed installation. The recommended approach would be to snapshot or backup the Virtual Machine(s) that host Cortex Gateway and SQL Server if this is possible. If this is not possible then the following steps should be taken: + +### Backup Git Repositories + +1. On the Web Application Server, if you do not know the location of the Repo folder you can check where it is located else skip to Step 2: + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. In File Explorer, navigate to the Repo Folder. +1. Copy the Repo folder to another location. + +### Backup SQL Server Databases + +Ensure that there are recent full backups of both the CortexWeb and CortexWeb.Auth Databases. For information on generating a full backup see Microsoft's guidance [here][Create Full DB Backup]. + +In the event of a failed installation contact [{{% ctx %}} Service Portal][CORTEX Service Portal] who will be able to assist with resolving the problems or with restoring the platform. + +## Domain Requirements + +All servers must be on the same domain and cannot be domain controllers. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|----------------------------|----------------|----------------|------------------| +| Windows Server 2003 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2003 R2 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2016 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2019 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2022.9 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for all of your servers (Web, Application and Load Balancer). + +## Licensing Requirements + +A valid {{% ctx %}} licence file and {{% ctx %}} Innovation with v7.2 feature identifier must be procured from {{% ctx %}}. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the Web Application server and it should contain fingerprints for the Web Application Server and each Application Server. + +To get a licence file and feature identifier take the following steps: + +1. Copy the following template to a text file: + + ```text + Web Application Server + MachineID: + Fingerprint: + + Application Server 1 + MachineID: + Fingerprint: + + Application Server 2 + MachineID: + Fingerprint: + + Application Server 3 + MachineID: + Fingerprint: + + Please also include a suitable {{% ctx %}} Innovation with v7.2 feature identifier. + ``` + +1. Extract `Cortex Innovation {{< version >}} - Licence Fingerprint Generator.zip`. +1. From that folder, copy `Cortex.Licensing.FingerprintGeneration.exe` to the Web Application server. +1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: WEBAPP-SERVER + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + +1. Copy the output (machine identifier and fingerprint) to the `Web Application Server` section of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server. +1. For each Application Server take the following steps: + 1. Copy `Cortex.Licensing.FingerprintGeneration.exe` to the Application server. + 1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: APP-SERVER1 + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + + 1. Copy the output (machine identifier and fingerprint) to one of the `Application Server` sections of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server. +1. Request a licence and feature identifier by raising a case in the [{{% ctx %}} Service Portal][CORTEX Service Portal], including the contents of the text file containing all of the fingerprint and machine information in the body of the case. +1. When the licence and feature identifier have arrived, copy the file `Cortex.lic` to `%ProgramData%\Cortex\Licences` on the Web Application Server, creating the `Cortex` and `Licences` folders if they don't exist. Save the feature identifier for use when [Upgrading Gateway][]. + +## Ensure correct owner of {{% ctx %}} Gateway Repo and Website folders + +In order for the upgrade to run smoothly, it is necessary to ensure that the owner and permissions of the Repo and Website folders are set correctly: + +1. If you do not know the location of the Repo folder you can check where it is located else skip to Step 2: + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. Navigate to the `Repo` folder, not opening it. +1. Right-click on the `Repo` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Click `Advanced` at the bottom of the dialog. +1. Check that the `Owner` is stated as the user that runs the {{% ctx %}} Gateway Application pool. If not change it: + 1. Next to the name of the current Owner, click `Change`. + 1. In the dialog enter the username of the user that runs the {{% ctx %}} Gateway Application pool. + 1. Click `Check Names` and ensure that the user is validated. + 1. Click `OK` on the Select User dialog. + 1. Select to `Replace owner on subcontainers and objects`. + 1. Click `OK` on the Advanced Security Settings dialog. +1. Check the `{{% ctx %}} Gateway Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `{{% ctx %}} Gateway Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `{{% ctx %}} Gateway Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. +1. Repeat these steps for the `Cortex` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex`, e.g. `C:\inetpub\wwwroot\Cortex`) + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Filesystem Requirements + +The Web Application Server, each Application Server and [gobetween][] Load Balancer Server (if used) must: + +* use an NTFS filesystem. +* enable Network Discovery and File Sharing + +To enable Network Discovery and File Sharing: + +1. Open File Explorer. +1. Click `Network` on the left. +1. A banner similar to the following will appear if Network Discovery and File Sharing is turned off: + {{< figure src="/images/Network Discovery 1.png" title="Network and File Discovery Disabled" >}} +1. Click the banner. +1. Click `Turn on network discovery and file sharing`: + {{< figure src="/images/Network Discovery 2.png" title="Enable Network and File Discovery" >}} + +## Service Requirements + +On the Web Application Server and each Application Server, the following Windows Services must be running: + +* Performance Logs & Alerts +* Remote Registry +* Windows Event Log + +## Security Requirements + +### Installation User + +On all Application Servers, Web Application Server and Load Balancer Server, a domain user, which is a member of the Local Administrators group, must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the HA platform that {{% ctx %}} Innovation is built upon. + +### Antivirus Exclusions + +It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the Web Application Server and each Application Server to reduce antivirus processing on Service Fabric artefacts: + +Folder Exclusions: + +* %ProgramFiles%\Microsoft Service Fabric +* %ProgramData%\SF +* %ProgramData%\SF\Logs + +Process Exclusions: + +* Fabric.exe +* FabricHost.exe +* FabricInstallerService.exe +* FabricSetup.exe +* FabricDeployer.exe +* ImageBuilder.exe +* FabricGateway.exe +* FabricDCA.exe +* FabricFAS.exe +* FabricUOS.exe +* FabricRM.exe +* FileStoreService.exe + +If you are using a built-in load balancer, it is advised that the following antivirus exclusions are created on the Load Balancer Server to reduce antivirus processing on service health checks: + +Process Exclusions: + +* gobetween.exe +* Cortex.Installation.HealthCheck.exe + +A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually. + +If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist. + +### Port Requirements + +{{% ctx %}} Innovation and Microsoft Service Fabric require a range of [firewall ports to be opened][Port Requirements] between the servers and specific services. + +If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in [Port Requirements][] to open the correct ports. + +The `Cortex.Innovation.Test.PortUsage.ps1` script is provided during installation to test the ports on the Web Application Server and each Application Server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible. + +### Certificate Requirements + +{{< alert title="Important" color="warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + +#### Application Servers + +{{% alert title="Note" %}} +For production platforms it is recommended that X.509 SSL multi-domain or wildcard certificates are obtained from a Certificate Authority and used for installation. For non-production platforms, certificates can be omitted from installation and it will create and use self-signed certificates. This may prevent 3rd parties that require valid certificate verification to access the API Gateway Service. +{{% / alert %}} + +An X.509 SSL multi-domain or wildcard certificate should be used to: + +* Secure communication between the load balancer and the nodes on the Application Servers. +* Secure communication between the Application Services. +* Allow Application Services to identify themselves to clients such as Gateway. +* Prevent unauthorised nodes from joining the HA cluster. +* Connect to Service Fabric Explorer from each of the Application Servers. + +The certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt](), and must meet the following requirements: + +* Subject field must be in one of the following formats depending on whether a multi-domain or wildcard certificate is used: + * Multi-domain certificate - If using the [gobetween][] load balancer this should be specified as the FQDN of the load balancer server (e.g. `CN=load-balancer.domain.com`). If using a different load balancer this must be specified as the FQDN of one of the application servers (e.g. `CN=application-server.domain.com`) + * Wildcard certificate - wildcard format, pertaining to the domain of the Application Servers (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. Additionally if using a multi-domain certificate: + * The FQDN, NetBIOS Name and IP address of all application servers must be added. + * Optionally, the FQDN, NetBIOS Name and IP address of the web application server must be added if the same certificate will be used for the [web application server][]. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +This file should be placed in a known location on the Application Server where the installation scripts will be run. This location will be required when running the installation script. + +If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject field can also be the FQDN of the load balancer (e.g. `CN=load-balancer.domain.com`). + +#### Web Application Server + +{{% ctx %}} Gateway requires an X.509 SSL certificate to be installed on the Web Application Server. This can be the same certificate as used for the application servers or a different certificate. + +The certificate must have the following properties: + +* Enhanced Key Usage: `Server Authentication` and `Client Authentication` +* Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1 + +If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error. + +{{% alert title="Important" color="warning" %}} +Multi-domain certificates, wildcard certificates, auto-generated self-signed certificates and {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" title="manually created self-signed certificates" >}} can be used. However, self-signed certificates are not recommended for production instances. +{{% /alert %}} + +More information about importing the certificate is given during installation. + +### TLS Requirements + +There is a set of non-compulsory security measures, recommended to be applied to the Web Application Server and each Application Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following: + +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + +See [SSL Best Practices][] for a full list of the security changes which will be applied. + +A script is provided during installation to apply these security changes: + +* For the Application servers: `Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1` +* For the Web Application Server: `Cortex.Innovation.Install.SSLBestPractices.ps1` + +### Encryption Requirements + +{{< section "/prerequisites/add-innovation-to-7.2/encryption-requirements.md">}} + +## Alternative Load Balancer Requirements + +Innovation has a [gobetween][] load balancer included that isn't highly available; It is possible to use an alternative. The requirements for installing an alternative load balancer are as follows: + +* Must support a round robin (or similar) method of load balancing to specified ports on 3 nodes. +* Must be able to health check each node by running a predefined batch script (`ApiGatewayTypeHealthcheck.bat`, which resides in the `gobetween` folder of the `Cortex Innovation {{< version >}} - App Server Install Scripts`) that returns 1 for healthy and 0 for unhealthy. +* Must be able to access each of the Application Servers via HTTPS. +* Ideally it should be highly available to avoid a single point of failure in the system. + +## Next Steps? + +1. [Install Application Servers and Load Balancer][] + +[alternative load balancer]: {{< ref "#alternative-load-balancer-requirements" >}} +[Anycast]: {{< url path="Anycast.MainDoc" >}} +[Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.Architecture" >}} +[C++ Redistributable]: {{< url path="MSDownload.CPlusPlusRedistributable.2013" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[gobetween]: {{< url path="GoBetween.MainDoc" >}} +[IIS Url Rewrite]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} +[Microsoft Server 2016]: {{< url path="MSEval.WindowsServer.2016" >}} +[Microsoft Server 2019]: {{< url path="MSEval.WindowsServer.2019" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Port Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.PortRequirements" >}} +[Recommended Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.RecommendedArchitecture" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Upgrading Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[web application server]: {{< ref "#web-application-server" >}} +[Web Deploy]: {{< url path="MSDownload.WebDeploy" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..bd73c1220 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,66 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} Innovation for the first time." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out a new Innovation installation to make sure it is working. + +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Dev` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Activity` 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. 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, 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 Flow` and `End Flow` 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 Variables Grid, set `Is Output Variable?` to `true` for the new `Result` variable. +1. Add a breakpoint to the `End Flow` block and start the flow. An execution token should appear. + If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][Troubleshooting Flow Not Starting]. +1. Select the execution in the Executions Grid (bottom panel). +1. The `Result` variable displayed in the Variables Viewer (right panel) should show the current time. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that either one or more of the parameters prefixed with `Service Fabric` in the `CortexGateway.SetParameters.xml` file was not set properly when updating Gateway, or the Application Services aren't healthy. See [Troubleshooting][Troubleshooting No Publish] for more information. + +## Test Executing Production Flows + +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +1. {{% ctx %}} Innovation has now been verified and is ready to use. + +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} +[Troubleshooting Flow No Blocks]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNoBlocks" >}} +[Troubleshooting Flow Not Starting]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNotStarting" >}} +[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" >}} +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.SetupGateway" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/_index.md new file mode 100644 index 000000000..24d0635d4 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/_index.md @@ -0,0 +1,12 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Information about adding {{% ctx %}} Innovation to {{% ctx %}} 7.2 on a single on-premise server without high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions." +weight: 10000 +--- + +{{% pageinfo %}} +Single server installations without HA are not recommended for the following scenarios: + +* Production installations that are required to scale and support HA +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/architecture.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/architecture.md new file mode 100644 index 000000000..62d3305f8 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/architecture.md @@ -0,0 +1,30 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended Innovation platform architecture, including component descriptions." +weight: 10 +--- + +# {{< param title >}} + +## Components + +{{< section "/architecture/components/single-server.md" >}} + +## Single Server Architecture + +{{% ctx %}} Innovation and v7.2 can run side-by-side, allowing flows to be built and run for both of them from the same Gateway instance. They each require a different set of back-end components to be installed. Innovation can be added to a {{% ctx %}} v7.2 installation by using the existing hardware. The only component shared by both Innovation and v7.2 is {{% ctx %}} Gateway. + +The minimum architecture for adding Innovation to a v7.2 Single Site, Single Server system is as follows: + +{{< figure src="/images/editable/Cortex Innovation v7.2 Single Server.png" class="centre" title="1 Server Architecture Diagram" >}} + +{{< section "/architecture/components/node-details.md" >}} + +{{% alert type="warning" title="Warning" %}} This architecture is not recommended for production platforms that are required to scale and support HA. Additionally, upgrades require application redeployment with downtime rather than using rolling upgrades. {{%/alert %}} + +## Next Steps? + +1. [Prerequisites][] + +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.Prerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-application-server.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-application-server.md new file mode 100644 index 000000000..e956aa8c2 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-application-server.md @@ -0,0 +1,64 @@ +--- +title: "Install Application Server" +linkTitle: "Install Application Server" +description: "Information about installing the Application Server." +weight: 30 +--- + +# {{< param title >}} + +This guide describes how to install the Application Server components on the server. Please ensure that the [Prerequisites][] have been read before starting this installation. + +## Make Installation Artefacts Available + +{{< section "/install-application-server/make-installation-artefacts-available.md">}} + +## Install Microsoft .NET Framework 4.7.2 + +{{< section "/install-application-server/install-dot-net-framework.md">}} + +## Apply Recommended Security Measures + +{{< section "/install-application-server/apply-recommended-security-measures.md">}} + +## Add Antivirus Exclusions + +If Windows Defender is not running on the server, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps: + +{{< section "/install-application-server/single-server/add-antivirus-exclusions.md">}} + +## Check Port Usage + +{{< section "/install-application-server/single-server/check-port-useage.md">}} + +## Configure Installation Script + +{{< section "/install-application-server/single-server/add-innovation-to-7.2/configure-installation-script.md">}} + +## Test Installation Script + +{{< section "/install-application-server/single-server/test-installation-script.md">}} + +## Run Installation Script + +{{< section "/install-application-server/single-server/run-installation-script.md">}} + +## Add Read and Execute access to Windows Crypto folder + +{{< section "/install-application-server/single-server/add-permissions-to-crypto-folder.md">}} + +## Check Application Services + +{{< section "/install-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Upgrade v7.2 Gateway to Include Innovation][] + +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.AntivirusExclusions" >}} +[Upgrade v7.2 Gateway to Include Innovation]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.AddInnovationTo72WebApplicationServer" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.Prerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-web-application-server.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-web-application-server.md new file mode 100644 index 000000000..4d86fba50 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/install-web-application-server.md @@ -0,0 +1,215 @@ +--- +title: "Upgrade v7.2 Gateway to Include Innovation" +linkTitle: "Upgrade v7.2 Gateway to Include Innovation" +description: "Information about upgrading v7.2 Gateway with Innovation functionality." +weight: 40 +--- + +# {{< param title >}} + +This guide describes how to upgrade Gateway on v7.2 to include Innovation. Please ensure that [Install Application Server][] has been completed before starting this installation. These steps assume that the v7.2 version of Gateway and its prerequisites have already been installed. + +The steps to add Innovation functionality to 7.2 are: + +1. Upgrade Gateway + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation {{< version >}} - Block Packages.zip + * Cortex Innovation {{< version >}} - Gateway.zip + * Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Install Prerequisites + +### Licensing + +Ensure that a valid {{% ctx %}} licence file named `Cortex.lic` exists on the server, in the location `%ProgramData%\Cortex\Licences`. If it does not, follow the instructions located at [Licensing Requirements][]. + +### Grant folder permissions to the {{% ctx %}} Gateway Application Pool User + +The following folders require `Modify` permission to allow creating the `NuGet` folders and its `NuGet.Config` file within: + +* `C:\Windows\System32\config\systemprofile\AppData\Roaming` +* `C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming` + +For each folder, perform the following steps: + +1. Navigate to the `AppData` folder. +1. Right-click on the `Roaming` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. +1. If the `Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. + +### Certificate Requirements + +In order to ensure that the correct certificate is used during the upgrade of {{% ctx %}} Gateway, it is necessary to [assign a friendly name][Assign Certificate Friendly Name] to the certificate that is currently being used for {{% ctx %}} Gateway. It is important to set the `ImportCertificate` parameter to `$false` when [configuring the {{% ctx %}} Gateway installation script][Configure CORTEX Gateway Installation Script]. + +#### Assign Certificate Friendly Name + +A Friendly Name should be assigned to the certificate being used for the Cortex Website. This will be used in the [Configure {{% ctx %}} Gateway Installation Script][Configure CORTEX Gateway Installation Script] to assign the correct certificate to the site: + +1. Click the Windows button (`Start`). +1. Type `certlm.msc` and press `Enter` to open the Certificate Manager dialog. +1. Expand `Personal` and select `Certificates`. +1. You should see your certificate in this store. +1. Right-click on the certificate and select `Properties`. +1. On the `General` tab in the `Friendly Name` text box, enter a name to be used for the certificate. +1. Click `OK`. + +## Perform Installation + +### Configure {{% ctx %}} Gateway Installation Script + +1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. + +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` + -FeatureFlags "InnovationId" ` + -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" ` + -ServiceFabricUsingSelfSignedCertificates $false ` + -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerEndpoint "https://server.domain.com:8722/api/" ` + -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` + -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFilePath "C:\Install\Certificate.pfx" ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | + |`FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} Innovation feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Licensing Requirements][], if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will overwrite the `FeatureFlags` value in the Gateway web.config.| + |`ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the server. The port should be specified as `8722` and there must be a trailing slash, e.g. `https://server.domain.com:8722/`.

This will overwrite the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Server][Configure Installation Script], `$true` if you used self-signed certificates.

This will overwrite the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricApiGatewayBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will overwrite the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will overwrite the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the server.

This will overwrite the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will overwrite the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will overwrite the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will overwrite the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that is used to run the {{% ctx %}} Gateway application pool currently.| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | This should be set to `$false` if the certificate is already imported.

Note that prior to installation the certificate must be [assigned a friendly name][Assign Certificate Friendly Name]. + |`CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged.| + |`CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false`, this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created Cortex site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +### Upgrade {{% ctx %}} Gateway + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to upgrade {{% ctx %}} Gateway. +1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +{{< alert type="note" title="Note" >}} It is recommended to choose to restart later after the final step of this section has completed to ensure that no issues occur.{{< /alert >}} + +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. This may take a few minutes. + +### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/add-innovation-to-7.2/grant-gateway-user-additional-folder-permissions.md">}} + +## Update Datasources and remove obsolete Database + +With effect from 2024.1 {{% ctx %}} Gateway no longer requires its own database unless the system is using LiveView or Reporting. If LiveView and Reporting are not used, some final steps are required to remove the obsolete database. + +To find out if LiveView or Reporting are used: + +1. In a browser navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway`, and log in as a user with administrative privileges. +1. Click on `Settings`. +1. In the submenu, click on `LDAP Authorisation`. +1. If any users have been granted permission to the LiveView or Reporting roles there will be a tick in the box. + +If no users are granted permission to the LiveView and Reporting roles: + +1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) +1. Open the `web.config` file. +1. Find the `connectionString` named `ModelDBContext`. +1. Change the connectionString parameter to be `connectionString="Data Source=None"` +1. Find the `connectionString` named `AuthContext`. +1. Change the connectionString parameter to be `connectionString="Data Source=None"` +1. Open `SQL Server Management Studio` and connect to the database instance with a user that has sysadmin privileges. +1. Expand the Server Name Node. +1. Expand the `Databases` Node. +1. Right Click on `CortexWeb` and select `Delete`. +1. In the `Delete Object` dialog box, select the checkbox to `Close Existing Connections` and click `OK`. + +## Preserve installation files + +Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates. + +## Next Steps? + +1. [Try it out][] + +[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Configure CORTEX Gateway Installation Script]: {{< ref "#configure-cortex-gateway-installation-script" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.ConfigureInstallationScript" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.InstallApplicationServer" >}} +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.LicensingRequirements" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.EncryptionRequirements" >}} +[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/prerequisites.md new file mode 100644 index 000000000..b17cb57a5 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/prerequisites.md @@ -0,0 +1,261 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- + +# {{< param title >}} + +The prerequisites required for a single server (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking installation. + +## Hardware Requirements + +{{% alert title="Note" %}}This configuration is not recommended for production servers that are required to scale and support HA.{{% /alert %}} + +| Server Role | Servers Required | CPU Cores (> 2GHz) | RAM (GB) | Disk (GB) | +|------------------|-----------------------|-----------------------------------|---------------|----------------------| +| Single Server
*Application Server +
Web Application Server* | 1 | 4+ *Recommended*
4 *Minimum* | 16+ *Recommended*
12 *Minimum* | 160+ *Recommended*
135 *Minimum*
30+ free on installation drive
40+ free on %ProgramData% drive | + +## Software Requirements + +| Server Role | Windows Server[^1] | .Net | PowerShell[^2] | IIS[^3] | Other Software | +|------------------|-------------------------|------|------------|---------|----------| +| Single Server
*Application Server +
Web Application Server* | [2019 (x64)][Microsoft Server 2019] *Recommended*
[2016 (x64)][Microsoft Server 2016] | [Framework 4.7.2][NET Framework 472] | 5.1 | 10.0.17763[^4]
10.0.14393[^5]
[URL Rewrite Module 2.1][IIS Url Rewrite] | [Microsoft Web Deploy 3.0 or later][Web Deploy]
[Visual C++ Redistributable 2013 (x64)][C++ Redistributable] | + +[^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. +[^2]: PowerShell 5.1 ships with Windows Server 2016 and 2019. +[^3]: IIS is supported; other web servers, including IIS Express are not supported. +[^4]: Ships as a windows role within Windows Server 2019. +[^5]: Ships as a windows role within Windows Server 2016. + +## Backup Requirements + +It is important to ensure that there are relevant backups in place to be able to restore the platform in the event of a failed installation. The recommended approach would be to snapshot or backup the Virtual Machine if this is possible. If this is not possible then the following steps should be taken: + +### Backup Git Repositories + +1. On the Web Application Server, if you do not know the location of the Repo folder you can check where it is located else skip to Step 2: + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. In File Explorer, navigate to the Repo Folder. +1. Copy the Repo folder to another location. + +### Backup SQL Server Databases + +Ensure that there are recent full backups of both the CortexWeb and CortexWeb.Auth Databases. For information on generating a full backup see Microsoft's guidance [here][Create Full DB Backup]. + +In the event of a failed installation contact [{{% ctx %}} Service Portal][CORTEX Service Portal] who will be able to assist with resolving the problems or with restoring the platform. + +## Domain Requirements + +The server must be on a domain and cannot be a domain controller. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|----------------------------|----------------|----------------|------------------| +| Windows Server 2003 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2003 R2 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2016 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2019 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2022.9 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server. + +## Licensing Requirements + +A valid {{% ctx %}} licence file and {{% ctx %}} Innovation feature identifier must be procured from {{% ctx %}}. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the server and it should contain that server's fingerprint. + +To get a licence file and feature identifier take the following steps: + +1. Copy the following template to a text file: + + ```text + Web Application/Application Server + MachineID: + Fingerprint: + + Please also include a suitable {{% ctx %}} Innovation feature identifier. + ``` + +1. Extract `Cortex Innovation {{< version >}} - Licence Fingerprint Generator.zip`. +1. From that folder, copy `Cortex.Licensing.FingerprintGeneration.exe` to the server. +1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: SERVER + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + +1. Copy the output (machine identifier and fingerprint) to the `Web Application/Application Server` section of the text file created in the initial step. Note that the machine identifier can be changed to any string. +1. Request a licence and feature identifier by raising a case in the [{{% ctx %}} Service Portal][CORTEX Service Portal], including the contents of the text file containing all of the fingerprint and machine information in the body of the case. +1. When the licence and feature identifier have arrived, copy the file `Cortex.lic` to `%ProgramData%\Cortex\Licences` on the Web Application Server, creating the `Cortex` and `Licences` folders if they don't exist. Save the feature identifier for use when [Upgrading Gateway][]. + +## Ensure correct owner of {{% ctx %}} Gateway Repo and Website folders + +In order for the upgrade to run smoothly, it is necessary to ensure that the owner and permissions of the Repo and Website folders are set correctly: + +1. If you do not know the location of the Repo folder you can check where it is located else skip to Step 2: + 1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`) + 1. Open the `web.config` file. + 1. Find the value of the `connectionString` named `CortexRepositories` +1. Navigate to the `Repo` folder, not opening it. +1. Right-click on the `Repo` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Click `Advanced` at the bottom of the dialog. +1. Check that the `Owner` is stated as the user that runs the {{% ctx %}} Gateway Application pool. If not change it: + 1. Next to the name of the current Owner, click `Change`. + 1. In the dialog enter the username of the user that runs the {{% ctx %}} Gateway Application pool. + 1. Click `Check Names` and ensure that the user is validated. + 1. Click `OK` on the Select User dialog. + 1. Select to `Replace owner on subcontainers and objects`. + 1. Click `OK` on the Advanced Security Settings dialog. +1. Check the `{{% ctx %}} Gateway Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user for Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. +1. If the `{{% ctx %}} Gateway Application Pool` user for Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `{{% ctx %}} Gateway Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. +1. Repeat these steps for the `Cortex` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex`, e.g. `C:\inetpub\wwwroot\Cortex`) + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Filesystem Requirements + +The server must use an NTFS filesystem. + +## Service Requirements + +The following Windows Services must be running on the server: + +* Performance Logs & Alerts +* Remote Registry +* Windows Event Log + +## Security Requirements + +### Installation User + +A domain user which is a member of the Local Administrators group on the server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the platform that {{% ctx %}} Innovation is built upon. + +### Antivirus Exclusions + +It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the server to reduce antivirus processing on Service Fabric artefacts: + +Folder Exclusions: + +* %ProgramFiles%\Microsoft Service Fabric +* %ProgramData%\SF +* %ProgramData%\SF\Logs + +Process Exclusions: + +* Fabric.exe +* FabricHost.exe +* FabricInstallerService.exe +* FabricSetup.exe +* FabricDeployer.exe +* ImageBuilder.exe +* FabricGateway.exe +* FabricDCA.exe +* FabricFAS.exe +* FabricUOS.exe +* FabricRM.exe +* FileStoreService.exe + +A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually. + +If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist. + +### Port Requirements + +{{% ctx %}} Innovation and Microsoft Service Fabric require a range of [firewall ports to be opened][Port Requirements] between the server and specific services. + +If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in [Port Requirements][] to open the correct ports. + +The `Cortex.Innovation.Test.PortUsage.ps1` script is provided during installation to test the ports on the server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible. + +### Certificate Requirements + +{{< alert title="Important" color="warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + +{{% alert title="Note" %}} +For production platforms it is recommended that an X.509 SSL certificate is obtained from a Certificate Authority and used for installation. For non-production platforms, certificates can be omitted from installation and it will create and use self-signed certificates. This may prevent 3rd parties that require valid certificate verification to access the API Gateway Service. +{{% / alert %}} + +An X.509 SSL certificate (standard or wildcard) should be used to: + +* Allow Application Services to identify themselves to clients such as Gateway. +* Prevent unauthorised nodes from joining the single node cluster. +* Connect to Service Fabric Explorer from the Application Server. +* Connect to Gateway. + +The certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt](), and must meet the following requirements: + +* Subject field must be in one of the following formats, depending on the certificate type: + * Standard certificates must use the standard format (e.g. `CN=host.domain.com`). + * Wildcard certificates must use the wildcard format, pertaining to the domain of the server (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. +* Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1. It must include any additional host names that should be able to be used to access the API Gateway Service. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +This file should be placed in a known location on the server. This location will be required when running the Application Server installation script. + +### TLS Requirements + +There is a set of non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following: + +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + +See [SSL Best Practices][] for a full list of the security changes which will be applied. The `Cortex.Innovation.Install.SSLBestPractices.ps1` script is provided during installation to apply these security changes to the server. + +### Encryption Requirements + +{{< section "/prerequisites/add-innovation-to-7.2/encryption-requirements.md">}} + +## Next Steps? + +1. [Install Application Server][] + +[Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.Architecture" >}} +[C++ Redistributable]: {{< url path="MSDownload.CPlusPlusRedistributable.2013" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Create Full DB Backup]: {{< url path="MSDocs.SqlServer.CreateFullDbBackup" >}} +[IIS URL Rewrite]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} +[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.InstallApplicationServer" >}} +[Microsoft Server 2019]: {{< url path="MSEval.WindowsServer.2019" >}} +[Microsoft Server 2016]: {{< url path="MSEval.WindowsServer.2016" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Port Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.PortRequirements" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Upgrading Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" >}} +[Web Deploy]: {{< url path="MSDownload.WebDeploy" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..fe7368ff4 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/try-it-out.md @@ -0,0 +1,66 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} Innovation for the first time." +weight: 60 +--- + +# {{< param title >}} + +This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that the [Gateway Upgrade][] has been completed before taking these steps. + +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Dev` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Activity` 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. 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, 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 Flow` and `End Flow` 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 Variables Grid, set `Is Output Variable?` to `true` for the new `Result` variable. +1. Add a breakpoint to the `End Flow` block and start the flow. An execution token should appear. + If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][Troubleshooting Flow Not Starting]. +1. Select the execution in the Executions Grid (bottom panel). +1. The `Result` variable displayed in the Variables Viewer (right panel) should show the current time. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that either one or more of the parameters prefixed with `Service Fabric` in the `CortexGateway.SetParameters.xml` file was not set properly when installing Gateway, or the Application Services aren't healthy. See [Troubleshooting][Troubleshooting No Publish] for more information. + +## Test Executing Production Flows + +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the server you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +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" >}} +[Gateway Upgrade]: {{< url path="Cortex.GettingStarted.OnPremise.AddInnovationTo72.SingleServerWithoutHA.AddInnovationTo72WebApplicationServer" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-interaction-portal-to-innovation/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-interaction-portal-to-innovation/_index.md new file mode 100644 index 000000000..a6737e5a7 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-interaction-portal-to-innovation/_index.md @@ -0,0 +1,8 @@ +--- +title: "Add Interaction Portal to Innovation" +linkTitle: "Add Interaction Portal to Innovation" +description: "Information about installing the {{% ctx %}} Interaction Portal for Innovation." +weight: 50 +--- + +* {{< filelink src="/pdf/Cortex Interaction Portal Deployment Guide.pdf" name="CORTEX Interaction Portal Deployment Guide" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/_index.md new file mode 100644 index 000000000..df43175cc --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/_index.md @@ -0,0 +1,10 @@ +--- +title: "Grafana" +linkTitle: "Grafana" +description: "Information about adding a Grafana platform to Innovation, including details about components, supported architectures, prerequisites, installation and configuration instructions." +weight: 10 +--- + +{{% pageinfo %}} +For instructions on how to set up Grafana and Grafana Loki in the cloud see {{< ahref path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.MainDoc" title="Grafana Cloud" >}}. +{{% /pageinfo %}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/_index.md new file mode 100644 index 000000000..b28eb4b81 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/_index.md @@ -0,0 +1,6 @@ +--- +title: "Advanced Setup" +linkTitle: "Advanced Setup" +description: "Supporting information about installing and configuring a Grafana observability platform for {{% ctx %}} Innovation." +weight: 90 +--- \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/port-requirements.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/port-requirements.md new file mode 100644 index 000000000..af97e8667 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/port-requirements.md @@ -0,0 +1,16 @@ +--- +title: "Port Requirements for the Web Application Server" +linkTitle: "Port Requirements for the Web Application Server" +description: "Information about the ports to be opened when installing the Grafana observability platform." +--- + +# {{% param title %}} + +All the required ports for the Web Application Server that forms part of the Grafana observability platform must be opened on any installed firewall. If any other firewall exists between the Application Servers and the Web Application Server, or Grafana users and the Web Application Server, it will be necessary to configure this selection of rules on it. These ports may be altered if there are any conflicts with other application requirements. + +## Grafana Observability Platform + +| Name | Description | Default Port(s) | Protocol | Direction | +|------|-------------|-----------------|----------|-----------| +| Grafana | The port used by the Grafana web application | 3000 | TCP | Inbound | +| Reverse proxy for Grafana Loki | The port used by IIS serving the role of a reverse proxy for Grafana Loki | 2100 | TCP | Inbound | diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/self-signed-certificates.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/self-signed-certificates.md new file mode 100644 index 000000000..61c6b388d --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/self-signed-certificates.md @@ -0,0 +1,239 @@ +--- +title: "Create Self-Signed Certificates" +linkTitle: "Create Self-Signed Certificates" +description: "Information about creating and installing self-signed certificates." +--- + +# {{% param title %}} + +Self-signed certificates should be generated using OpenSSL which is bundled in the {{% ctx %}} Web Application Server Installation Scripts: + +## Setup OpenSSL in PowerShell + +1. Open a Windows PowerShell (x64) window as administrator. +1. Make a directory in which to store the certificates by running the following command, changing the path as required: + + ```powershell + mkdir C:\Certificates + ``` + +1. Navigate PowerShell to inside the certificates folder created above, using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Certificates" + ``` + +1. Temporarily add OpenSSL to the Path environment variable of your system by running the following command, modifying the path according to the location of `openssl.exe` in the installation scripts on the machine: + + ```powershell + $env:PATH += ";C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts\OpenSSL" + ``` + +## Generate the Root CA Certificate + +1. Create the root CA private key by running the following command: + + ```powershell + openssl genrsa -out cortexCA.key 4096 + ``` + +1. Generate the root CA certificate signed with the private key: + 1. Copy the following text into a text editor: + + ```shell + RANDFILE = .rnd + [ ca ] + default_ca = CA_default # The default ca section + [ CA_default ] + # Directory and file locations. + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + policy = policy_strict + [ policy_strict ] + # The root CA should only sign intermediate certificates that match. + # See the POLICY FORMAT section of `man ca`. + countryName = match + stateOrProvinceName = match + organizationName = match + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + [ req ] + # Options for the `req` tool (`man req`). + default_bits = 2048 + distinguished_name = req_distinguished_name + string_mask = utf8only + + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + # Extension to add when the -x509 option is used. + x509_extensions = v3_ca + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_min = 2 + countryName_max = 2 + stateOrProvinceName = State or Province Name (full name) + localityName = Locality Name (eg, city) + 0.organizationName = Organization Name (eg, company) + organizationalUnitName = Organizational Unit Name (eg, section) + commonName = Common Name (eg, your website's domain name) + commonName_max = 64 + emailAddress = Email Address + emailAddress_max = 40 + # Optionally, specify some defaults. + countryName_default = GB + stateOrProvinceName_default = Hampshire + localityName_default = Southampton + 0.organizationName_default = Cortex Ltd + organizationalUnitName_default = We Are CORTEX + commonName_default = Cortex CA + emailAddress_default = Hello@WeAreCORTEX.com + [ v3_ca ] + # Extensions for a typical CA (`man x509v3_config`). + subjectKeyIdentifier = hash + authorityKeyIdentifier = keyid:always,issuer + basicConstraints = critical, CA:true + keyUsage = critical, digitalSignature, cRLSign, keyCertSign + ``` + + 1. Save the file as `ca.cnf` in the directory created for the certificates above. + 1. In the PowerShell window, run the following command: + + ```powershell + openssl req -sha256 -x509 -new -nodes -key cortexCA.key -days 3650 -out cortexCA.pem -config ca.cnf + ``` + + 1. Press `Enter` for all parameters except the Common Name. For this enter `Cortex CA`. + +1. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command: + + ```powershell + openssl pkcs12 -export -inkey cortexCA.key -in cortexCA.pem -out cortexCA.pfx + ``` + +1. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr. + +## Import the Root CA Certificate + +1. Double click on the `cortexCA.pfx` file in the certificates folder to import the certificate into the Windows Certificate Store. +1. Select `Local Machine` then click `Next`. +1. Click `Next`. +1. Enter the Export Password which the certificate was generated with then click `Next`. +1. Select `Place all certificates in the following store`. +1. Click `Browse…`. +1. Select `Trusted Root Certification Authorities`, click `OK` then click `Next`. +1. Click `Finish`. + +## Generate the Certificate + +1. Create a private key for the SSL cert by running the following command: + + ```powershell + openssl genrsa -out cortex.key 2048 + ``` + +1. Generate the SSL certificate request: + 1. Copy the following text into a text editor: + + ```shell + RANDFILE = .rnd + [ ca ] + default_ca = CA_default # The default ca section + [ CA_default ] + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + policy = policy_loose + [ policy_loose ] + # Allow the intermediate CA to sign a more diverse range of certificates. + # See the POLICY FORMAT section of the `ca` man page. + countryName = optional + stateOrProvinceName = optional + localityName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + [ req ] + # Options for the `req` tool (`man req`). + default_bits = 2048 + distinguished_name = req_distinguished_name + string_mask = utf8only + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + # Extension to add when the -x509 option is used. + x509_extensions = v3_req + req_extensions = v3_req + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_min = 2 + countryName_max = 2 + stateOrProvinceName = State or Province Name (full name) + localityName = Locality Name (eg, city) + 0.organizationName = Organization Name (eg, company) + organizationalUnitName = Organizational Unit Name (eg, section) + commonName = Common Name (eg, your website's domain name) + commonName_max = 64 + emailAddress = Email Address + emailAddress_max = 40 + # Optionally, specify some defaults. + countryName_default = GB + stateOrProvinceName_default = Hampshire + localityName_default = Southampton + 0.organizationName_default = Cortex Ltd + organizationalUnitName_default = We Are CORTEX + commonName_default = CortexServerCertificate + emailAddress_default = Hello@WeAreCORTEX.com + [ v3_req ] + basicConstraints = CA:FALSE + keyUsage = nonRepudiation, digitalSignature, keyEncipherment + subjectAltName = @alt_names + [ alt_names ] + # Specify all DNS and/or IP addresses that clients can use to access the secured resource. + DNS.1 = MACHINE-NAME + DNS.2 = FULLY QUALIFIED MACHINE NAME / WILDCARD DOMAIN NAME + DNS.3 = localhost + IP.1 = IP ADDRESS + IP.2 = 127.0.0.1 + ``` + + 1. Modify the section `[alt_names]` to include all the required DNS names and IP addresses that clients can use to access the secured resource. + Each DNS name or IP address entry must be suffixed with `.N` where `N` is the unique index of the DNS name or IP address entry; see below for examples: + | Resource URL | Configuration to add | + |---------------------------------------|-----------------------------------| + | `https://wearecortex.com/gateway` | `DNS.1 = wearecortex.com` | + | `https://internal.wearecortex.com/gateway` | `DNS.2 = internal.wearecortex.com`
`or`
`DNS.2 = *.wearecortex.com` | + | `https://10.0.0.0/gateway` | `IP.1 = 10.0.0.0` | + | `https://192.168.1.100/gateway` | `IP.2 = 192.168.1.100` | + + 1. Save the file as `san.cnf` in the directory created for the certificates above. + 1. In the PowerShell window, run the following command: + + ```powershell + openssl req -new -sha256 -key cortex.key -out cortex.req -extensions v3_req -config san.cnf + ``` + + 1. Press `Enter` for everything. The Common Name must stay as `CortexServerCertificate`. + 1. Sign the request with a previously generated root CA by running the following command: + + ```powershell + openssl x509 -req -sha256 -in cortex.req -CA cortexCA.pem -CAkey cortexCA.key -CAcreateserial -out cortex.pem -days 3650 -extensions v3_req -extfile san.cnf + ``` + + 1. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command: + + ```powershell + openssl pkcs12 -export -inkey cortex.key -in cortex.pem -out cortex.pfx + ``` + + 1. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr. + +## Import the Certificate + +1. Double click on the `cortex.pfx` file in the certificates folder to get the certificate imported to the Windows Certificate Store. +1. Select `Local Machine` then click `Next`. +1. Click `Next`. +1. Enter the Export Password which the certificate was generated with then click `Next`. +1. Select `Place all certificates in the following store`. +1. Click `Browse…`. +1. Select `Personal`, click `OK` then click `Next`. +1. Click `Finish`. diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/ssl-best-practices.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/ssl-best-practices.md new file mode 100644 index 000000000..eb94f280e --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/advanced/ssl-best-practices.md @@ -0,0 +1,83 @@ +--- +title: "SSL Best Practices" +linkTitle: "SSL Best Practices" +description: "Information about the recommended security settings for the Grafana observability platform servers." +--- + +# {{% param title %}} + +A collection of registry settings can be applied during installation to guarantee your server is only using the recommended encryption algorithms and TLS protocols: + +| Type | Name | Enabled | +| --------------------- | ----------------------------------------| ----------- | +| Ciphers | AES 128/128 | ✓ | +| | AES 256/256 | ✓ | +| | Triple DES 168 | ✓ | +| | DES 56/56 | ✕ | +| | NULL | ✕ | +| | RC2 128/128 | ✕ | +| | RC2 40/128 | ✕ | +| | RC2 56/128 | ✕ | +| | RC4 128/128 | ✕ | +| | RC4 40/128 | ✕ | +| | RC4 56/128 | ✕ | +| | RC4 64/128 | ✕ | +| | | | +| Hashes | MD5 | ✕ | +| | SHA | ✓ | +| | SHA256 | ✓ | +| | SHA384 | ✓ | +| | SHA512 | ✓ | +| | | | +| KeyExchangeAlgorithms | Diffie-Hellman | ✓ | +| | ECDH | ✓ | +| | PKCS | ✓ | +| | | | +| Protocols | Multi-Protocol Unified Hello | ✕ | +| | PCT 1.0 | ✕ | +| | SSL 2.0 | ✕ | +| | SSL 3.0 | ✕ | +| | TLS 1.0 | ✕ | +| | TLS 1.1 | ✕ | +| | TLS 1.2 | ✓ | +| | | | +| Cipher Suites | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ✓ | +| | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ✓ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA25 | ✕ | +| | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_RSA_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_RSA_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_256_CBC_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_RSA_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_RSA_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_RSA_WITH_3DES_EDE_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 | ✕ | +| | TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_DHE_DSS_WITH_AES_256_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_AES_128_CBC_SHA | ✕ | +| | TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA | ✕ | +| | TLS_RSA_WITH_RC4_128_SHA | ✕ | +| | TLS_RSA_WITH_RC4_128_MD5 | ✕ | +| | TLS_RSA_WITH_NULL_SHA256 | ✕ | +| | TLS_RSA_WITH_NULL_SHA | ✕ | +| | TLS_PSK_WITH_AES_256_GCM_SHA384 | ✕ | +| | TLS_PSK_WITH_AES_128_GCM_SHA256 | ✕ | +| | TLS_PSK_WITH_AES_256_CBC_SHA384 | ✕ | +| | TLS_PSK_WITH_AES_128_CBC_SHA256 | ✕ | +| | TLS_PSK_WITH_NULL_SHA384 | ✕ | +| | TLS_PSK_WITH_NULL_SHA256 | ✕ | + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on other applications as well as their communication capabilities with third party systems and services. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/architecture.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/architecture.md new file mode 100644 index 000000000..68470e7d1 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/architecture.md @@ -0,0 +1,40 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended architecture for a Grafana platform installation." +weight: 10 +--- + +# {{% param title %}} + +## Components + +| Component | Purpose | Required/Optional |Server Role | +|-----------|---------|----------|------------| +| [Grafana][] | Web application that provides querying and visualisation of data in the form of dashboards. | Required | Web Application Server | +| [Grafana Loki][] | Log aggregation system designed to store and query logs from applications and infrastructure. | Required | Web Application Server | +| [Microsoft Internet Information Services (IIS)][IIS] | Web server used as a reverse proxy for Grafana Loki. | Required | Web Application Server | +| [Promtail][] | An agent which ships the contents of local logs to a Grafana Loki instance. It should be deployed to every machine that has a Microsoft Service Fabric node used by Innovation. | Required | Application Server | + +## Recommended Architecture + +{{% alert title="Note" %}} +For production systems it is recommended to {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallOnNewHardware" title="install on new hardware" >}}. However, if additional hardware is not available, you can {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallOnExistingHardware" title="install on existing hardware" >}}. +{{% /alert %}} + +The following architecture requires 1 + 1..n servers: + +* 1 x Web Application Server which contains Grafana, Grafana Loki and Microsoft IIS. +* 1..n x Application Servers. + +{{< figure src="/images/editable/Grafana Platform Architecture Diagram - On-Premise.png" >}} + +## Next Steps? + +1. [Prerequisites][] + +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}} +[Grafana]: {{< url path="Grafana.Products.Grafana.MainDoc" >}} +[Grafana Loki]: {{< url path="Grafana.Products.Loki.MainDoc" >}} +[Promtail]: {{< url path="Grafana.Products.Loki.Promtail.MainDoc" >}} +[IIS]: {{< url path="IIS.MainDoc" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/_index.md new file mode 100644 index 000000000..61d057022 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/_index.md @@ -0,0 +1,6 @@ +--- +title: "Install Grafana" +linkTitle: "Install Grafana" +description: "Information about installing and configuring Grafana on the Web Application Server." +weight: 30 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/configure-grafana.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/configure-grafana.md new file mode 100644 index 000000000..e5b54c9ba --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/configure-grafana.md @@ -0,0 +1,67 @@ +--- +title: "Configure Grafana" +linkTitle: "Configure Grafana" +description: "Information about configuring Grafana on the Web Application Server." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to configure Grafana on the Web Application Server. + +## Log-in and Change the Password + +It is required that on the first log in into Grafana, a new password for the admin user is set up. +The password should be different from the default one. + +1. On the Web Application Server open a web browser. +1. Browse to `http://localhost:3000/`. +1. On the login page, enter `admin` for the username and password. +1. Click Log in. +1. Set a new password for the admin user when prompted to do so. + +## Configure HTTPS + +By default Grafana allows access over the unsecure HTTP protocol. This needs to be modified to allow access only over the secure HTTPS protocol. + +1. Locate `sample.ini` file in the `grafana\conf` subfolder in the location Grafana was installed to; by default `C:\Program Files\GrafanaLabs\grafana\conf\sample.ini`. +1. Copy `sample.ini` and paste it in the same location renaming it to `custom.ini`. +1. Run a text editor in administrator mode. +1. In the text editor open the `custom.ini` Grafana configuration file. +1. In the `server` section uncomment the `protocol` option and set it to HTTPS, e.g.: + + ```yaml + # Protocol (http, https, h2, socket) + protocol = https + ``` + +1. In the `server` section uncomment the `cert_file` and `cert_key` options and set them to the certificate `.pem` and `.key` filenames and path saved to during the [Certificate Requirements][] step e.g.: + + ```yaml + # https certs & key file + cert_file = C:\certificates\certificate.pem + cert_key = C:\certificates\certificate.key + ``` + +1. Save the file. +1. Open the Services app. +1. Restart the Grafana service. + +## Verify That HTTPS Works + +It is important to verify that Grafana is only accessible through HTTPS. + +1. On the Web Application Server open a web browser. +1. Browse to `http://localhost:3000/`. +1. Browser should not be able to make a connection to Grafana and a default error page should be displayed. +1. Browse to `https://localhost:3000/`. +1. On the login page, enter `admin` as the username and the corresponding password. +1. Click Log in. +1. You should have successfully logged into Grafana. + +## Next Steps? + +1. [Install Grafana Loki][] + +[Install Grafana Loki]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.MainDoc" >}} +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.WebAppCertificateRequirements" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/install-grafana.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/install-grafana.md new file mode 100644 index 000000000..ab29b8dac --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-grafana/install-grafana.md @@ -0,0 +1,24 @@ +--- +title: "Install Grafana" +linkTitle: "Install Grafana" +description: "Information about installing Grafana on the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to install Grafana on the Web Application Server. Please ensure that the [Prerequisites][] have been completed before starting this installation. + +## Install Grafana + +1. Download the [Grafana 10.4.1][] Windows installer. +1. Run the installer and install Grafana to a suitable location. + +## Next Steps? + +1. [Configure Grafana][] + +[Configure Grafana]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallGrafana.ConfigureGrafana" >}} +[Grafana 10.4.1]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaWebApp.10.4.1.Windows" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}} +[Software Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.SoftwareRequirements" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/_index.md new file mode 100644 index 000000000..b4bb93257 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/_index.md @@ -0,0 +1,6 @@ +--- +title: "Install Grafana Loki" +linkTitle: "Install Grafana Loki" +description: "Information about installing and configuring Grafana Loki on the Web Application Server." +weight: 40 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/configure-loki.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/configure-loki.md new file mode 100644 index 000000000..3db8584be --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/configure-loki.md @@ -0,0 +1,132 @@ +--- +title: "Configure Loki" +linkTitle: "Configure Loki" +description: "Information about configuring Grafana Loki on the Web Application Server." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to configure Grafana Loki on the Web Application Server. + +{{% alert type="note" title="Note" %}}For security reasons, Grafana Loki should be run behind an encrypted and authenticated reverse proxy as it does not provide these features by itself.{{% /alert %}} + +## Install Certificate + +IIS requires the X.509 SSL certificate, obtained in the [prerequisites][], to be installed on the Web Application Server. + +You can import the certificate by right clicking the certificate file, selecting `Install Certificate` and following the wizard. When prompted, ensure you import it into the `Local Machine` store and not `Current User`. + +To verify the certificate is imported: + +1. Click the Windows button (`Start`) +2. Type `certlm.msc` and press `Enter` to open the Certificate Manager dialog +3. Expand `Personal` and select `Certificates` +4. You should see your certificate in this store + +## Setup Reverse Proxy with IIS + +All of the steps must be carried out on the Web Application Server. + +### Install IIS Basic Authentication + +1. Run *Server Manager*. +1. Expand the *Manage* menu and select *Add Roles and Features*. +1. In the left-hand menu, select *Server Selection*. +1. Select the name of the Web Application Server, click *Next*. +1. On the *Server Roles* page, in the *Roles* tree, expand *Web Server (IIS)* --> *Web Server* --> *Security*. +1. Select *Basic Authentication*, click *Next*. +1. Click *Next* to get to the *Confirm installation selections* page. +1. Click *Install*. +1. Click *Close* on the *Results* page. + +### Install IIS URL Rewrite Module + +1. Download the [URL Rewrite module 2.1][] +1. Run the downloaded installer. +1. When prompted by the Web Platform Installer, click *Install*. +1. On the *Prerequisites* page click *I Accept* to agree to the license terms for the module. +1. Once the install has completed, click *Finish*. +1. Click *Exit* to close the Web Platform Installer. + +### Install Application Request Routing + +1. Download [Application Request Routing 3.0][] +1. Run the downloaded installer. +1. When prompted by the Web Platform Installer, click *Install*. +1. On the *Prerequisites* page click *I Accept* to agree to the license terms for the module. +1. Once the install has completed, click *Finish*. +1. Click *Exit* to close the Web Platform Installer. + +### Set Up Reverse Proxy + +To set up a reverse proxy, carry out the following configuration. + +#### Add a New Website + +1. Run IIS Manager. +1. In the *Connection* pane, expand the server. +1. Right-click on *Sites* and select *Add Website...* from the menu. +1. In the *Add Website* window: + - Provide the site name, e.g. `Grafana Loki`. + - Set the *Physical path* to the location where the site will be stored and ensure that the path exists, e.g. `C:\inetpub\wwwroot\Grafana Loki`. + - For *Binding* set: + - *Type*: `https` + - *IP address*: `All unassigned` + - *Port*: `2100` + - *Host name*: The fully qualified domain name of the Web Application Server. This must match one of the Subject Alternative Names in the SSL certificate selected in the next step. + - *SSL certificate*: Select the certificate created as part of the [Certificate Requirements][prerequisites] instructions. + - Click *OK* to add the website. + +#### Enable Basic Authentication + +1. In the *Connection* pane, browse to *Sites*. +1. Select the newly created website. +1. Double-click on the *Authentication* icon. +1. Disable *Anonymous Authentication*. +1. Enable *Basic Authentication*. + +## Configure URL Rewrite Rule + +1. In the *Connection* pane, browse to *Sites*. +1. Select the newly created website. +1. Double-click on the *URL Rewrite* icon. +1. In the *Actions* pane, click *Add Rule(s)...*. +1. Select *Reverse Proxy* from the *Inbound and Outbound Rules* section. +1. Click *OK*. +1. If prompted to *Add Reverse Proxy Rules*, click *OK* to enable proxy functionality. +1. In the *Inbound Rules* section enter `localhost:3100` as the server name. +1. Ensure that *Enable SSL Offloading* is checked. +1. Click *OK*. + +#### Restart the Website + +1. In the *Connection* pane, browse to *Sites*. +1. Select the newly created website. +1. In the *Manage Website* pane, click *Restart*. + +#### Create Loki User + +1. Run Windows PowerShell as Administrator. +1. Execute the following command to create a new local user on the Web Application Server: + + ```Powershell + New-LocalUser "" -Password (ConvertTo-SecureString "" -AsPlainText -force) -FullName "" -Description "" –PasswordNeverExpires + ``` + + | Parameter | Description | + |------|-------------| + | username | The username of the user to be created. | + | password | The password for the user account. | + | name | The full name for the user account. | + | description | The description of the user account. | + +## Next Steps? + +1. [Install Promtail][] + +[Application Request Routing 3.0]: {{< url path="IIS.Downloads.ApplicationRequestRouting-3_0" >}} +[Install Promtail]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallPromtail.MainDoc" >}} +[prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.WebAppCertificateRequirements" >}} +[Software Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.SoftwareRequirements" >}} +[URL Rewrite module 2.1]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/install-loki.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/install-loki.md new file mode 100644 index 000000000..e1d70e6fd --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/install-loki.md @@ -0,0 +1,32 @@ +--- +title: "Install Loki" +linkTitle: "Install Loki" +description: "Information about installing Grafana Loki on the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to install Grafana Loki on the Web Application Server. Please ensure that the [Prerequisites][] have been completed before starting this installation. + +## Install Grafana Loki + +1. Download [Grafana Loki 3.0.0][] archive. +1. Extract content of the downloaded archive to a suitable location, e.g. `C:\Program Data\Cortex\Observability\Loki`. +1. Download the [Grafana Loki Install.zip][] archive and extract its contents alongside the previously extracted Grafana Loki `loki-windows-amd64.exe`. +This archive contains the `loki-local-config.yaml` configuration file, [NSSM][] (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Grafana Loki as a Windows service. +1. Run Windows PowerShell as Administrator. +1. Change the location to where all the files were extracted to in step 2, e.g. `cd "C:\Program Data\Cortex\Observability\Loki"`. +1. Execute the `.\Install-Loki.ps1` command to install the downloaded Grafana Loki `loki-windows-amd64.exe` as a service. +1. Execute the `.\Start-Loki.ps1` command to start the Grafana Loki service. + +## Next Steps? + +1. [Configure Loki][] + +[Configure Loki]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.ConfigureLoki" >}} +[Grafana Loki 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaLoki.3.0.0.GrafanaLokiInstallZip" >}} +[Grafana Loki Install.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaLokiInstallZip" >}} +[NSSM]: {{< url path="NSSM.MainDoc" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}} +[Software Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.SoftwareRequirements" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/_index.md new file mode 100644 index 000000000..6f53df537 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/_index.md @@ -0,0 +1,6 @@ +--- +title: "Install Promtail" +linkTitle: "Install Promtail" +description: "Information about installing and configuring Promtail on the Application Server(s)." +weight: 50 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md new file mode 100644 index 000000000..3e9433911 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/configure-promtail.md @@ -0,0 +1,80 @@ +--- +title: "Configure Promtail" +linkTitle: "Configure Promtail" +description: "Information about configuring Promtail on the Application Server(s)." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to configure Promtail on the Application Server(s). + +{{% alert type="note" title="Note" %}}These steps must be performed for every Promtail installation in the cluster.{{% /alert %}} + +## Install Certificate + +If a self-signed certificate was obtained in the [prerequisites][], the CA certificate used to create this certificate must be imported on each Application Server. Otherwise, Promtail will not be able to establish communication with Grafana Loki. + +To import the CA certificate: + +1. Copy the `cortexCA.pfx` CA certificate created during the [root CA certificate generation][Generate The Root CA Certificate] steps into a suitable location on the Application Server. +1. Double click on the `cortexCA.pfx` file to import the certificate into the Windows Certificate Store. +1. Select `Local Machine` then click `Next`. +1. Click `Next`. +1. Enter the Export Password which the certificate was generated with then click `Next`. +1. Select `Place all certificates in the following store`. +1. Click `Browse…`. +1. Select `Trusted Root Certification Authorities`, click `OK` then click `Next`. +1. Click `Finish`. + +## Configure Promtail + +### Set Client URL for Grafana Loki + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Set the Grafana Loki `URL` in the `clients` section. + + The following template has been provided for convenience: + `https://:@:/loki/api/v1/push` +| Element | Description | +|------|-------------| +| username | The username of the user created during [Create Loki User][] steps. | +| password | The password which was set for the user during [Create Loki User][] steps. | +| loki host address | The host address of the machine where the Grafana Loki reverse proxy was configured during [Add a New Website][] steps . This must match the configured host name. | +| loki reverse proxy port | The port of the Grafana Loki reverse proxy configured during [Add a New Website][] steps. Usually 2100. | + + A correct URL should be similar to `https://username:password@hostaddress:2100/loki/api/v1/push`. +1. Save the file. + +### Set the positions.yaml File Path + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Set the `filename` in the `positions` section to the location where you want the `positions.yaml` file to be created on Promtail startup, e.g. `C:/Program Data/Cortex/Observability/Promtail/Positions.yaml`. +1. Create all the folders of the path specified in the previous step. +1. Save the file. + +{{% alert title="Note" %}} +If the specified path to the folder for the `positions.yaml` file doesn't exists, the file will not get created on Promtail startup. +{{% /alert %}} + +### Set the Path to the API Gateway Service Log Files + +1. Open the `promtail-local-config.yaml` configuration file, which is located in the folder alongside the `promtail-windows-amd64.exe` file. +1. Set the `__path__` in the `static_configs` > `targets` > `labels` section to the path of the `Logs` folder specified in the `appSettings.json` file during installation of the API Gateway Service, e.g. `"C:/ProgramData/Cortex/API Gateway Service/Logs/**/ServiceFabricHttpEventLog-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]{_[0-9][0-9][0-9],}.json"`. +1. Save the file. + +### Start Promtail + +1. Run Windows PowerShell as Administrator. +1. Change the location to the folder where the `promtail-windows-amd64.exe` file is located. +1. Execute the `.\Start-Promtail.ps1` command to start the Promtail Windows service. + +## Next Steps? + +1. [Setup Grafana][] + +[Add a New Website]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.AddANewWebsite" >}} +[Create Loki User]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.CreateLokiUser" >}} +[Generate The Root CA Certificate]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Advanced.GenerateTheRootCaCertificate" >}} +[prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.WebAppCertificateRequirements" >}} +[Setup Grafana]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.SetupGrafana" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md new file mode 100644 index 000000000..9d257e4ad --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md @@ -0,0 +1,31 @@ +--- +title: "Install Promtail" +linkTitle: "Install Promtail" +description: "Information about installing Promtail on the Application Server(s)." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to install Promtail on the Application Server(s). Please ensure that the [Prerequisites][] have been completed before starting this installation. + +## Install Promtail + +1. Download [Promtail 3.0.0][] archive. +1. Extract content of the downloaded archive to a suitable location, e.g. `C:\Program Data\Cortex\Observability\Promtail`. +1. Download the [Promtail Install.zip][] archive and extract its contents alongside the previously extracted Promtail `promtail-windows-amd64.exe`. +This archive contains the `promtail-local-config.yaml` configuration file, [NSSM][] (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Promtail as a Windows service. +1. Run Windows PowerShell as Administrator +1. Change the location to where all the files were extracted to in step 2, e.g. `cd "C:\Program Data\Cortex\Observability\Promtail"`. +1. Execute the `.\Install-Promtail.ps1` command to install the downloaded `promtail-windows-amd64.exe` as a service. + +## Next Steps? + +1. [Configure Promtail][] + +[Configure Promtail]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallPromtail.ConfigurePromtail" >}} +[NSSM]: {{< url path="NSSM.MainDoc" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}} +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[Promtail Install.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}} +[Software Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.SoftwareRequirements" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/prerequisites.md new file mode 100644 index 000000000..9900a21d1 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/prerequisites.md @@ -0,0 +1,170 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- +# {{% param title %}} + +The prerequisites required for each server role (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking the installation. + +## Hardware Requirements + +{{% alert title="Note" %}} +For production systems it is recommended to {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallOnNewHardware" title="install on new hardware" >}}. However, if additional hardware is not available, you can {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallOnExistingHardware" title="install on existing hardware" >}}. +{{% /alert %}} + +### Option 1: Install on New Hardware + +The following hardware requirements are recommended for production systems: + +| Server Role | Servers Required | CPU Cores (> 2GHz) | RAM (GB) | Disk (GB) | +|------------------|-----------------------|-----------------------------------|---------------|----------------------| +| Web Application Server | 1 | 4+ *Recommended*
2 *Minimum* | 16+ *Recommended*
8 *Minimum* | 50+ (SSD) *Recommended*
40 (HDD) *Minimum*
5+ free on installation drive | + +### Option 2: Install on Existing Hardware + +If additional hardware is not available, it is possible to install to the same Web Application server that hosts {{% ctx %}} Gateway. + +The table below specifies additional resources that are recommended to be added to the existing Web Application server: + +| Server Role | Additional CPU Cores (> 2GHz) | Additional RAM (GB) | Additional Disk (GB) | +|------------------|-----------------------------------|---------------|----------------------| +| Web Application Server
(Shared with {{% ctx %}} Gateway) | 4+ *Recommended*
2 *Minimum* | 12+ *Recommended*
6 *Minimum* | 10+ *Recommended*
5 *Minimum*| + +{{% alert title="Note" %}} +The application servers (as described in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.Architecture" title="Architecture" >}}) to which Promtail will be added have already been installed as part of the Innovation install process and do not require any hardware modifications for the observability platform installation. +{{% /alert %}} + +## Software Requirements + +| Server Role | Windows Server[^1] | IIS[^2] | Other Software | +|------------------|-------------------------|---------|----------| +| Web Application Server | [2022 (x64)][] *Recommended*
[2019 (x64)][] | 10.0.20348[^3]
10.0.17763[^4]
IIS Basic Authentication[^5]
[URL Rewrite module 2.1][] | [Grafana 10.4.1][] *Enterprise Edition*
[Grafana Loki 3.0.0][]| +| Application Server | [2022 (x64)][] *Recommended*
[2019 (x64)][] | | [Promtail 3.0.0][]| + +[^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. +[^2]: IIS is supported; other web servers, including IIS Express are not supported. +[^3]: Ships as a windows role within Windows Server 2022. +[^4]: Ships as a windows role within Windows Server 2019. +[^5]: Installed during the [Install IIS Basic Authentication][] configuration steps. + +## Domain Requirements + +All servers must be on the same domain and cannot be domain controllers. + +## Web Browser Requirements + +Grafana supports the latest versions of the following browsers: + +* Chrome/Chromium +* Firefox +* Safari +* Microsoft Edge + +{{% alert title="Note" %}} +Always enable JavaScript in your browser. Running Grafana without JavaScript enabled in the browser is not supported. +{{% / alert %}} + +## Additional Web Application Server Requirements + +### Security Requirements + +#### Installation User + +A domain user which is a member of the Local Administrators group on the Web Application Server must be available to perform the installation. + +#### Port Requirements + +The observability platform requires a range of [firewall ports to be opened][Port Requirements] on the Web Application Server. + +#### Certificate Requirements + +{{% alert title="Note" %}} +For production systems, it is recommended that X.509 SSL certificates are obtained from a Certificate Authority and used for installation. For non-production systems, self-signed certificates may be used. Details on how to create a self-signed certificate can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Advanced.CreateSelfSignedCertificates" title="Create Self-Signed Certificates" >}}. +{{% / alert %}} + +An X.509 SSL certificate (standard, wildcard or self-signed) should be used to secure communication between: + +* Promtail on the Application Servers and the reverse proxy configured for Grafana Loki on the Web Application Server. +* Grafana end users and the Grafana Web Application on the Web Application Server. + +The wildcard certificate used for installing Innovation can be used if it is available in the .PEM file format, otherwise a new certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt][], and must meet the following requirements: + +* Subject field must be in one of the following formats, depending on the certificate type: + * Standard certificates must use the standard format (e.g. `CN=host.domain.com`). + * Wildcard certificates must use the wildcard format, pertaining to the domain of the Web Application Server (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the Grafana Web Application. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must also be available in a .PEM file format. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. + +The files should be placed in a known location on the Web Application Server. This location will be required when [configuring Grafana to use HTTPS][]. + +More information about importing the certificate is given during [installation][]. + +#### TLS Requirements + +A set of non-compulsory security measures is recommended to be applied to the Web Application Server to prevent attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following: + +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + +See [SSL Best Practices][] for a full list of the recommended security changes to be applied. + +##### Apply Recommended Security Measures + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on other applications as well as their communication capabilities with third party systems and services. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} + +Apply the settings by following these instructions: + +1. Copy from one of the application servers the `Cortex.Innovation.Install.SSLBestPractices.ps1` file extracted during the [Make Installation Artefacts Available][] step into a suitable location on the Web Application Server. +1. Open a Windows PowerShell (x64) window as administrator. +1. Change the location to the folder where the `Cortex.Innovation.Install.SSLBestPractices.ps1` file was copied to using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install" + ``` + +1. Run the `Cortex.Innovation.Install.SSLBestPractices.ps1` script using the following command: + + ```powershell + .\Cortex.Innovation.Install.SSLBestPractices.ps1 + ``` + +1. To use all the recommended settings click `Apply all` to the first prompt. + + To selectively apply each setting select `Choose which to apply`. Each change will then be prompted with a Yes/No confirmation before applying. +1. Restart the machine when the script asks. + +## Additional Application Server Requirements + +These requirements apply to each of the Application Servers. + +### Security Requirements + +#### Installation User + +A domain user which is a member of the Local Administrators group on all Application Servers must be available to perform the installation. + +## Next Steps? + +1. [Install Grafana][] + +[2019 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2019" >}} +[2022 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2022" >}} +[Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Architecture" >}} +[configuring Grafana to use HTTPS]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallGrafana.ConfigureHTTPS" >}} +[Create Self-Signed Certificates]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Advanced.CreateSelfSignedCertificates" >}} +[Make Installation Artefacts Available]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.MakeInstallationArtefactsAvailable" >}} +[Grafana 10.4.1]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaWebApp.10.4.1.Windows" >}} +[Grafana Loki 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaLoki.3.0.0.GrafanaLokiInstallZip" >}} +[Install Grafana]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallGrafana.MainDoc" >}} +[Install IIS Basic Authentication]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.InstallIISBasicAuthentication" >}} +[installation]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.InstallCertificate" >}} +[Let’s Encrypt]: {{< url path="LetsEncrypt.MainDoc" >}} +[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Advanced.SSLBestPractices" >}} +[URL Rewrite module 2.1]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} +[Port Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Advanced.PortRequirements" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/setup-grafana.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/setup-grafana.md new file mode 100644 index 000000000..254282ac3 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/setup-grafana.md @@ -0,0 +1,84 @@ +--- +title: "Setup Grafana" +linkTitle: "Setup Grafana" +description: "Information about setting up Grafana to communicate with the installed Grafana Loki as well as importing and configuring the default set of dashboards." +weight: 60 +--- + +# {{% param title %}} + +This guide describes where to get the default {{% ctx %}} Innovation Dashboards from and how to import them for use in Grafana. + +Please ensure that the Installations for [Grafana][] and [Loki][] have been completed before starting this section. + +## Configure Loki Data Source in Grafana + +1. Log in to your configured Grafana instance with a user that has the *admin* role. +1. In Grafana, go to *Connections* > *Data Sources* via the menu on the left sidebar. +1. Click the *+ Add new data source* button. +1. Choose *Loki* from the *Logging & document databases* section of the list. +1. Configure the data source as follows: + + | Option | Description | Value | + |---------|-------------|---------| + | Name | The name of the data source to use in Grafana | `Cortex Loki` | + | URL | The address of your Grafana Loki Server | `http://localhost:3100` | + | Timeout | The HTTP request timeout in seconds set to the same value as configured in the Grafana Loki `loki-local-config.yaml` configuration file as `query_timeout` in the `limits_config` configuration section, located alongside the Grafana Loki `loki-windows-amd64.exe` file. | `600` | + +1. Click *Save and Test*. +1. *Data source successfully connected.* message should be displayed above the *Save and Test* + +## Download the {{% ctx %}} Innovation Default Dashboards + +1. Download [Grafana.Dashboards.zip] archive containing the {{% ctx %}} Innovation default dashboards. +1. Extract the content of the downloaded archive to a suitable location. + +## Create Folder for Dashboards + +1. Log in to your configured Grafana with a user that has the *Admin* role. +1. In Grafana, go to *Dashboards* via the menu on the left sidebar. +1. Click the *New* button and select *New folder* from the drop-down menu. +1. Enter a folder name, e.g. `Cortex`. +1. Click *Create*. + +## Import Dashboards + +1. Log in to your configured Grafana with a user that has the *Admin* role. +1. Go to *Dashboards* via the menu on the left sidebar. +1. Click the *New* button and select *Import* from the drop-down menu. +1. Click the *Upload JSON file* button. +1. Locate the `Flow Execution Requests.json` file extracted from the downloaded `Grafana.Dashboards.zip`. +1. Select the file and click *Open*. +1. Select the folder in Grafana you wish the dashboard to be saved in, e.g. *Cortex*. +1. Select your configured Loki data source from the dropdown menu. +1. Click *Import*. +1. Repeat steps 2 - 8 for the `Platform Health.json` file. + +## Configure Data Sources + +It is necessary to update the Custom Filter inside the dashboards to use the correct data source. + +To do this, follow these steps for all default {{% ctx %}} Innovation dashboards imported: + +1. Log in to your configured Grafana with a user that has the *Admin* role. +1. To open a dashboard: + 1. Go to *Dashboards* via the menu on the left sidebar. + 1. Click the folder name that the dashboards were imported to. + 1. Click the *Flow Execution Requests* dashboard to open it. +1. Open the *Dashboard settings* menu via the cog icon in the top right-hand side of the dashboard. +1. Click *Variables* from the top menu of the *Settings* page. +1. Click *CustomFilter* at the bottom of the *Variables* list. +1. Select your configured Loki data source in the *Ad-hoc options* > *Data source* drop-down menu. +1. Click *Apply*. +1. Click the dashboard name in the breadcrumb at the top left corner of the page to go back to the dashboard. +1. Click the + icon next to the Custom Filter to confirm that a list of available filter options is visible. +1. Repeat steps 2 - 9 for the *Platform Health* dashboard. + +## Next Steps? + +1. [Try it Out][] + +[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaDashboardsZip" >}} +[Grafana]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallGrafana.MainDoc" >}} +[Loki]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.MainDoc" >}} +[Try it Out]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.TryItOut" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/try-it-out.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/try-it-out.md new file mode 100644 index 000000000..59731451b --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/Grafana/try-it-out.md @@ -0,0 +1,47 @@ +--- +title: "Try it Out" +linkTitle: "Try it Out" +description: "Information about trying out Grafana Observability Dashboards for the first time." +weight: 60 +--- + +# {{% param title %}} + +## Check Dashboards are Displaying Data + +{{% alert title="Note" %}} +This test uses the test flow published as part of testing the Innovation installation. See {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.TryItOutPublishedFlow" title="Testing HA installation" >}} or {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.TryItOutPublishedFlow" title="Testing non-HA installation" >}}. An alternative flow can be used that exists on the system and can be executed. +{{% / alert %}} + +1. Open an HTTP client, such as [Postman][]. Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | For HA installation use:
`https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`
e.g. `https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage`

For non-HA installation use:
`https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`
e.g. `https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage`| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services. See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.| + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted). See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.| + + {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you may need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. Once the request has completed, using a web browser, log in to your configured Grafana. +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Flow Execution Requests* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} +1. Open the *Dashboards* page via the menu on the left sidebar. +1. Click the folder name that the dashboards were imported to. +1. Click the *Platform Health* dashboard to open it. +1. The request made at step 1 should be visible on the dashboard. +{{% alert title="Note" %}} +If other requests have been made then there may be more than one request visible on the dashboard. +{{% / alert %}} + +[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScript" >}} +[Non-HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScript" >}} +[Postman]: {{< url path="Postman.Downloads.MainDoc" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/_index.md b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/_index.md new file mode 100644 index 000000000..ab5ea38be --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/add-observability-to-innovation/_index.md @@ -0,0 +1,6 @@ +--- +title: "Add Observability to Innovation" +linkTitle: "Add Observability to Innovation" +description: "Information about installing an observability platform for Innovation." +weight: 30 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/_index.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/_index.md new file mode 100644 index 000000000..926f2c897 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/_index.md @@ -0,0 +1,10 @@ +--- +title: "Install Innovation Only" +linkTitle: "Install Innovation Only" +description: "Information about installing a {{% ctx %}} Innovation platform." +weight: 10 +--- + +{{% pageinfo %}} +{{% ctx %}} Innovation can be deployed on-premise across [multiple servers](multiple-server-with-ha) to provide improved scale and high availability (HA), or to a [single server](single-server-without-ha) if scale and HA aren't required. +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/_index.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/_index.md new file mode 100644 index 000000000..f42adde16 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/_index.md @@ -0,0 +1,6 @@ +--- +title: "Advanced Setup" +linkTitle: "Advanced Setup" +description: "Supporting information about installing {{% ctx %}} Innovation with non-default configurations." +weight: 90 +--- diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/advanced-config-changes.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/advanced-config-changes.md new file mode 100644 index 000000000..a89321ee5 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/advanced-config-changes.md @@ -0,0 +1,207 @@ +--- +title: "Advanced Application Server and Load Balancer Configuration Changes" +linkTitle: "Advanced Application Server and Load Balancer Configuration Changes" +description: "Information about installing {{% ctx %}} Innovation with non-default installation values." +--- + +# {{% param title %}} + +Advanced configuration (such as port changes) can be undertaken by taking the following steps before running the PowerShell script. Some values will be modified by the script and they will take precedence, but those parameters can be removed from the script and this file used entirely if required. + +## Multiple Server With HA + +1. In the `Cortex Innovation {{< version >}} - Installation Scripts` folder, locate the file `Cortex.Innovation.Install.Config.json` and open it with a text editor. +1. Change the configuration file according to your cluster, referring to the following example and details: + + {{< highlight json "linenos=table,hl_lines=4 17 18 21 22 23 27-28 31-32 35-36 42 44 46 48 50 52 73-75 80-82,linenostart=1" >}} + { + "customers": [ + { + "name": "Customer1", + "isPrimary": true, + "rules": { + "clientConnectionEndpointPort": "8001", + "clusterConnectionEndpointPort": "8002", + "leaseDriverEndpointPort": "8003", + "serviceConnectionEndpointPort": "8004", + "httpGatewayEndpointPort": "9080", + "reverseProxyEndpointPort": "9081", + "applicationPorts": "10010-10500", + "ephemeralPorts": "10501-20000" + }, + "loadBalancer": { + "installDirectory": "%ProgramData%\\loadbalancer", + "iPAddress": "192.168.20.178", + "loadBalancerSnmpPort": "162", + "snmpReceiverServicePort": "10001", + "loadBalancerTlsPort": "443", + "apiGatewayServicePort": "8722", + "adminCertificate": "loadBalancerCertificate" + }, + "servers": [ + { + "serverName": "app-server1", + "iPAddress": "192.168.1.1" + }, + { + "serverName": "app-server2", + "iPAddress": "192.168.1.2" + }, + { + "serverName": "app-server3", + "iPAddress": "192.168.1.3" + } + ] + } + ], + "servers": { + "app-server1": { + "faultDomain": "fd:/fd1", + "serverCertificate": "serverCert" + }, + "app-server2": { + "faultDomain": "fd:/fd2", + "serverCertificate": "serverCert" + }, + "app-server3": { + "faultDomain": "fd:/fd3", + "serverCertificate": "serverCert" + } + }, + "rules": { + "windowsSmbRemoteRegistry": [ + "135", + "137", + "138", + "139", + "445" + ], + "rabbitMqAmqpPorts": [ + "5671" + ], + "rabbitMqEpmdPort": "4369", + "rabbitMqErlangDistributionClientPorts": "35672-35682", + "rabbitMqErlangDistributionServerPort": "25672", + "rabbitMqManagementApiPort": "15671" + }, + "serverCertificates": { + "serverCert": { + "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx", + "pfxCertificatePassword": "#_121004188127116!133150189159197057145221234081254~237141201182240!228132117152122101166250091035249#", + "pemRootCertificatePath": "" + } + }, + "adminCertificates": { + "loadBalancerCert": { + "pfxCertificatePath": "C:\\Certificates\\lbCert.pfx", + "pfxCertificatePassword": "#_121004188127116!133150189159197057145221234081254~237141201182240!228132117152122101166250091035249#", + "pemRootCertificatePath": "" + } + } + } + {{< / highlight >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Line | Description | + |------|-------------| + |4 | A name identifying the platform being installed. This should have no spaces or symbols. It will be appended to the node names that are displayed in the Service Fabric management tool. | + |16-24 | If the bundled load balancer is not being used, delete these lines | + |17 | A local empty or non-existent directory on the load balancer server that the load balancer can be installed in. The directory path will be created if it does not exist. The installation user must have permissions to create and write to directories here. Ensure that all backslashes are escaped with another backslash. Environment variables may be used. | + |18 | The IPv4 address of the server that the load balancer should run on. | + |21 | The port that the HTTPS load balancer server should run on. This port should not be in use by anything else. | + |22 | The port that the API Gateway Service is running on the Application Servers. This should be 8722. | + |23 | The name of a certificate entry in the adminCertificates section. If this line is removed, an auto-generated self-signed certificate will be used. | + |27, 31, 35 | The short computer names of the Application Servers. These must not contain the domain. The installation will be run on the first of these nodes. | + |28, 32, 36 | The respective IPv4 addresses of the Application Servers. | + |42, 46, 50 | These keys should be changed to the computer names of the Application Servers to match those on lines 26, 30 and 24 | + |44, 48, 52 | The name of a certificate entry in the serverCertificates section. This should be the same for all Application Servers. If these lines are removed, an auto-generated self-signed certificate will be used. Self-signed certificates are not recommended for production systems.| + |73-75 | Skip configuring these lines if self-signed certificates are being used. | + |80-82 | Skip configuring these lines if self-signed certificates are being used or if the bundled load balancer is not being used. | + |73 |This is the local path of a .PFX certificate file on the first Application Server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used. | + |74 |The password used to secure the .PFX file.

{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |75 |This only needs to be used if the installation has failed due to a missing root certificate. See [Troubleshooting Root Certificate Error] for information.| + |80 |This is the local path of a .PFX certificate file on the first Application Server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used. | + |81 |The password used to secure the .PFX file.

{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |82 |This only needs to be used if the installation has failed due to a missing root certificate. See [Troubleshooting Root Certificate Error] for information.| + +1. Save and close the config file. + +## Single Server Without HA + +1. In the `Cortex Innovation {{< version >}} - Installation Scripts` folder, locate the file `Cortex.Innovation.Install.Config.json` and open it with a text editor. +1. Change the configuration file according to your cluster, referring to the following example and details: + + {{< highlight json "linenos=table,hl_lines=4 18 19 25 27 48-50,linenostart=1" >}} + { + "customers": [ + { + "name": "Customer1", + "isPrimary": true, + "rules": { + "clientConnectionEndpointPort": "8001", + "clusterConnectionEndpointPort": "8002", + "leaseDriverEndpointPort": "8003", + "serviceConnectionEndpointPort": "8004", + "httpGatewayEndpointPort": "9080", + "reverseProxyEndpointPort": "9081", + "applicationPorts": "10010-10500", + "ephemeralPorts": "10501-20000" + }, + "servers": [ + { + "serverName": "app-server1", + "iPAddress": "192.168.1.1" + } + ] + } + ], + "servers": { + "app-server1": { + "faultDomain": "fd:/fd1", + "serverCertificate": "serverCert" + } + }, + "rules": { + "windowsSmbRemoteRegistry": [ + "135", + "137", + "138", + "139", + "445" + ], + "rabbitMqAmqpPorts": [ + "5671" + ], + "rabbitMqEpmdPort": "4369", + "rabbitMqErlangDistributionClientPorts": "35672-35682", + "rabbitMqErlangDistributionServerPort": "25672", + "rabbitMqManagementApiPort": "15671" + }, + "serverCertificates": { + "serverCert": { + "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx", + "pfxCertificatePassword": "#_121004188127116!133150189159197057145221234081254~237141201182240!228132117152122101166250091035249#", + "pemRootCertificatePath": "" + } + } + } + {{< / highlight >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Line | Description | + |------|-------------| + |4 | A name identifying the platform being installed. This should have no spaces or symbols. It will be appended to the node names that are displayed in the Service Fabric management tool. | + |18 | The short computer names of the node. This must not contain the domain. The installation will be run on the this node. | + |19 | The IPv4 address of the node. | + |25 | This key should be changed to the computer names of the node to match that on line 18 | + |27 | The name of a certificate entry in the serverCertificates section. If this line is removed, an auto-generated self-signed certificate will be used. Self-signed certificates are not recommended for production systems.| + |48-50 | Skip configuring these lines if self-signed certificates are being used. | + |48 |This is the local path of a .PFX certificate file on the server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used. | + |49 |The password used to secure the .PFX file.

{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |50 |This only needs to be used if the installation has failed due to a missing root certificate. See [Troubleshooting Root Certificate Error] for information.| + +1. Save and close the config file. + +[Troubleshooting Root Certificate Error]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingNoRootCertificate" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/configure-firewalls.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/configure-firewalls.md new file mode 100644 index 000000000..31120acd4 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/configure-firewalls.md @@ -0,0 +1,23 @@ +--- +title: "Configure Firewalls" +linkTitle: "Configure Firewalls" +description: "Information about configuring Firewalls, e.g. adding rules." +--- + +# {{% param title %}} + +## Add Inbound Rules to Windows Firewall + +To set up inbound rules for Windows Firewall take the following steps for each rule that you want to add: + +1. Navigate to `Start` → `Administrative Tools` → `Windows Firewall with Advanced Security`. +1. In the left-hand panel, click on the `Inbound Rules` node. +1. In the right-hand panel, click on `New Rule`. +1. In the New Inbound Rule Wizard, select the `Port` option then click on the `Next >` +button. +1. Select either `TCP` or `UDP` depending on the rule that is being made. +1. Select `Specific local ports`. +1. Enter the required ports in a comma separated list (e.g. `443, 80`) in the text box and press `Next >`. +1. Select `Allow the connection` then click `Next >`. +1. Click `Next >` again, then add an identifiable name for the rule +1. Click `Finish`. diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/encrypt-text.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/encrypt-text.md new file mode 100644 index 000000000..42dd5fa94 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/encrypt-text.md @@ -0,0 +1,33 @@ +--- +title: "Encrypt Text" +linkTitle: "Encrypt Text" +description: "Information about encrypting text using the {{% ctx %}} Encryptor." +--- + +# {{% param title %}} + +To encrypt text using the {{% ctx %}} Encryptor PowerShell module: + +1. Extract the `Cortex Innovation {{< version >}} - Encryptor.zip` file to a folder with the same name. +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Encryptor` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Encryptor" + ``` + +1. In the Windows PowerShell (x64) window, run the following command to import the module: + + ```powershell + Import-Module .\Cortex.Encryptor.psd1 + ``` + +1. In the Windows PowerShell (x64) window, run the following command to encrypt text, replacing `text to encrypt` with the text that you want to encrypt: + + ```powershell + ConvertTo-EncryptedText -Text 'text to encrypt' + ``` + + The command will return the encrypted text, beginning with `#_`. This step can be repeated for any texts that need to be encrypted. + + {{< alert title="Note:" >}}The `Import-Module` command will need to be repeated every time a new PowerShell window is used. To install the PowerShell module so that it is always available, follow the instructions laid out {{< ahref path="MSDocs.PowerShell.InstallModule" title="here" >}}.{{< /alert >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/port-requirements.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/port-requirements.md new file mode 100644 index 000000000..db6b50350 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/port-requirements.md @@ -0,0 +1,80 @@ +--- +title: "Port Requirements for Application Servers and Load Balancer" +linkTitle: "Port Requirements for Application Servers and Load Balancer" +description: "Information about the ports opened when installing {{% ctx %}} Innovation." +--- + +# {{% param title %}} + +{{% ctx %}} Innovation and Microsoft Service Fabric open a range of firewall ports between the servers and specific services. Some of them are opened during installation, others are opened dynamically as needed. These are opened on Windows Firewall. If any other firewall exists between the servers, it will be necessary to configure this selection of rules on it. Most ports may be altered if another program overlaps with them, the description will say if this is not possible. + +## {{% ctx %}} Innovation Ports + +| Name | Description | Default Port(s) | Protocol | Direction | +|------|-------------|-----------------|----------|-----------| +| Cortex.RabbitMqAmqpPorts | The port used by AMQP 0-9-1 and 1.0 clients with TLS. **This cannot currently be changed.** | 5671 | TCP | Inbound | +| Cortex.RabbitMqEpmdPorts | The port used by epmd, a peer discovery service used by RabbitMQ nodes and CLI tools. **This cannot currently be changed.** | 4369 | TCP | Inbound | +| Cortex.RabbitMqErlangDistribut ionClientPorts | The ports used by CLI tools (Erlang distribution client ports) for communication with nodes and is allocated from a dynamic range (computed as Erlang dist port + 10000 through dist port + 10010). **This cannot currently be changed.** | 35672-35682 | TCP | Inbound | +| Cortex.RabbitMqErlangDistribut ionServerPort | The port used for RabbitMQ inter-node and CLI tools communication (Erlang distribution server port) and is allocated from a dynamic range (limited to a single port by default, computed as AMQP port + 20000). **This cannot currently be changed.** | 25672 | TCP | Inbound | +| Cortex.RabbitMqManagement ApiPort | The port used by the RabbitMQ management plugin. **This cannot currently be changed.** | 15671 | TCP | Inbound | +| Cortex.WindowsSmbRemote Registry | The ports used by Windows SMB and Remote Registry service. | 135, 137, 138, 139, 445 | TCP | Inbound | +| Cortex.ServiceFabric.Customer1. ClusterConnectionEndpointPort | The port used by the client to connect to the cluster when client APIs are used. | 8001 | TCP | Inbound | +| Cortex.ServiceFabric.Customer1. ClientConnectionEndpointPort | The port where the nodes communicate with each other. | 8002 | TCP | Inbound | +| Cortex.ServiceFabric.Customer1. ServiceConnectionEndpointPort | The port used by the applications and services deployed on a node to communicate with the Service Fabric client on that particular node. | 8004 | TCP | Inbound | + +## Microsoft Service Fabric Firewall Rules (present on all Application Servers, with Domain, Public and Private Profiles) + +These rules will all appear in Windows Firewall with names starting with ‘{CustomerName}.{NodeName} WindowsFabric’. + +|Name in Rule | Name in Config | Description | Default Port(s) | Protocol(s) | Direction | +|-------------|----------------|-------------|-----------------|-------------|-----------| +| Application Processes | application Ports | The ports that are used by the Service Fabric applications. Service Fabric uses these ports whenever new dynamic ports are required. **The application port range should be large enough to cater for the dynamic port allocation of the application. Currently at least 400 is recommended. This may change if new services are added. This range should not overlap the Dynamic Ports (ephemeralPorts) range as set in the configuration.**

**Program**: Any | 10010-10500 | TCP, UDP | Inbound, Outbound | +| BackupRestore Service Process | N/A | The port used by the Service Fabric process which manages the backup and restore of Application Services.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_\\BRS.Code.Current\\FabricBRS.exe | Any | TCP | Inbound, Outbound | +| CentralSecret Service Process | N/A | The port used by the Service Fabric process which manages secrets.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_\\BRS.Code.Current\\FabricCSS.exe | Any | TCP | Inbound, Outbound | +| DCA Process | N/A | The port used by the Service Fabric Diagnostics Collection Agent, which manages Diagnostic data.

**Program:** %ProgramFiles%\\Microsoft Service Fabric\\bin\\ Fabric\\DCA.Code\\FabricDCA.exe | Any | TCP | Outbound | +| Dynamic Ports | ephemeral Ports | Override the **[dynamic ports used by the OS][Dynamic Ports]**. Service Fabric uses a part of these ports as application ports, and the remaining are available for the OS. It also maps this range to the existing range present in the OS, so for all purposes, you can use the ranges given in the sample JSON files. **Make sure that the difference between the start and the end ports is at least 255**. You might run into conflicts if this difference is too low, because this range is shared with the OS. To see the configured dynamic port range, run netsh int ipv4 show dynamicport tcp.

**Program:** Any | 10501-20000 | TCP, UDP | Inbound, Outbound | +| EventStore Service Process | N/A | The port used by the Service Fabric EventStore, which maintains events about the state of the Application Services.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\ES.Code.Current\\ EventStore.Service.exe | Any | TCP | Inbound, Outbound | +| Fabric Gateway Process | N/A | The port used by the Service Fabric Gateway, which allows REST and management functions to access the Application Services.

**Program:** %ProgramFiles%\\Microsoft Service Fabric\\bin\\Fabric\\ Fabric.Code\\FabricGateway.exe | Any | TCP | Inbound, Outbound | +| Fabric Process | N/A | The port used by the main Service Fabric service.

**Program:** %ProgramFiles%\\Microsoft Service Fabric\\bin\\Fabric\\ Fabric.Code\\Fabric.exe | Any | TCP | Inbound, Outbound | +| FabricUpgrade Service Process | N/A | The port used by the Service Fabric Upgrade service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\US.Code.Current\\FabricUS.exe | Any | TCP | Inbound, Outbound | +| FaultAnalysis Service Process | N/A | The port used by the Service Fabric Fault Analysis service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\FAS.Code.Current\\FabricFAS.exe | Any | TCP | Inbound, Outbound | +| FileStore Service Process | N/A | The port used by the Service Fabric File Store service, which manages the application file store and image store.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\FileStoreService.Code.Current\\ FileStoreService.exe | Any | TCP | Inbound, Outbound | +| GatewayResource Manager Process | N/A | The port used by the Service Fabric Gateway Resource Manager, which provides APIs to manage the Application Services and other resources.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\GRM.Code.Current\\FabricGRM.exe | Any | TCP | Inbound, Outbound | +| HTTP App Gateway | reverse Proxy Endpoint Port | **This port cannot be changed at the current time. If it is already in use, please contact {{% ctx %}} for assistance.** The reverse proxy endpoint. For more information, see **[Service Fabric reverse proxy][]**.

**Program:** Any | 9081 | TCP | Inbound, Outbound | +| Http Gateway | http Gateway Endpoint Port | The port used by Service Fabric Explorer to connect to the cluster. **This changes the port used to connect to the Service Fabric management portal as part of the post-install checks.**

**Program:** Any | 9080 | TCP | Inbound, Outbound | +| Infrastructure Service Process | N/A | The port used by the Service Fabric Infrastructure Service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\IS.Code.Current\\FabricIS.exe | Any | TCP | Inbound, Outbound | +| Lease Driver | lease Driver Endpoint Port | The port used by the cluster lease driver to find out if the nodes are still active.

**Program:** Any | 9002 | TCP | Inbound, Outbound | +| ManagedIdentity TokenService Process | N/A | The port used by the Service Fabric Managed Identity Token Service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\MITS.Code.Current\\ ManagedIdentityTokenService.exe | Any | TCP | Inbound, Outbound | +| RepairManager Service Process | N/A | The port used by the Service Fabric Repair Manager Service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\RM.Code.Current\\FabricRM.exe | Any | TCP | Inbound, Outbound | +| Upgrade Orchestration Service Process | N/A | The port used by the Service Fabric Upgrade Orchestration service.

**Program:** %ProgramData%\\SF\\.\\Fabric\\work\\Applications\\ \_\_FabricSystem\_App*\\UOS.Code.Current\\FabricUOS.exe | Any | TCP | Inbound, Outbound | + +## Application Service Rules + +Each service has an endpoint which is used to communicate with Service Fabric and the RabbitMQ message broker. These are configured in the ServiceManifest.xml file within each package in the ApplicationPackages\Cortex directory of the installation media. These ports cannot be used by any other program. If they do clash with another program, they may be changed but additional configuration changes may be necessary, as described in the description of each port. The Application ports must not lie in the `ephemeralPorts` range. + +| Name of Service | Description | Default Port(s) | Protocol(s) | Direction | Program | +|--------------------------|--------------------------------------------------------------------------------|--------------------------------------|-------------|-------------------|---------| +| API Gateway | {{< section "/port-requirements/description/api-gateway.md" >}} | 8722 | TCP, UDP | Inbound, Outbound | Any | +| Authorisation | {{< section "/port-requirements/description/authorisation.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Configuration Management | {{< section "/port-requirements/description/configuration-management.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Data Storage | {{< section "/port-requirements/description/data-storage.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Execution | {{< section "/port-requirements/description/execution.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Execution Management | {{< section "/port-requirements/description/execution-management.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Licence Management | {{< section "/port-requirements/description/licence-management.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Package Management | {{< section "/port-requirements/description/package-management.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Provisioning | {{< section "/port-requirements/description/provisioning.md" >}} | Dynamic – Uses the application ports | N/A | N/A | N/A | +| Triggers (SNMP) | {{< section "/port-requirements/description/triggers-snmp.md" >}} | 10001 | UDP | Inbound | Any | + +## Load Balancer Rules + +{{% alert title="Note" %}}Only applicable for installations with HA.{{% /alert %}} + +The load balancer server must be able to retrieve traffic via HTTPS. The following firewall ports are opened by the installer (these rules will all appear in Windows Firewall with names starting with `{CustomerName}`): + +|Name in Rule | Name in Config | Default Port(s) | Protocol(s) | Direction | Program | +|--------------------|----------------------|-----------------|-------------|-----------|---------| +| GoBetweenTlsPort | loadBalancerSnmpPort | 162 | UDP | Inbound | Any | +| GoBetweenTlsPort | loadBalancerTlsPort | 443 | TCP | Inbound | Any | + +[Dynamic Ports]: {{< url path="MSSupport.Troubleshooting.DynamicPorts" >}} +[Service Fabric reverse proxy]: {{< url path="MSDocs.ServiceFabric.ReverseProxy" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/rollover-certificates.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/rollover-certificates.md new file mode 100644 index 000000000..46a45d5b8 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/rollover-certificates.md @@ -0,0 +1,166 @@ +--- +title: "Rollover CA certificates" +linkTitle: "Rollover CA certificates" +description: "Information about updating the certificates on a single or multi-server {{% ctx %}} platform which uses CA certificates." +--- + +# {{% param title %}} + +{{% pageinfo %}} +This process MUST be undertaken before certificates expire, otherwise your system will become unusable. If certificates have already expired, contact {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} at the earliest opportunity. + +Only platforms which use CA certificates can have their certificates updated using this mechanism. Systems using self-signed certificates must be reinstalled. + +This mechanism cannot be used to switch from self-signed to CA certificates; that requires a reinstall. +{{% /pageinfo %}} + +{{% alert type="warning" title="Warning" %}}Updating the certificates on a single-server system with no high availability will result in downtime while the upgrade takes place. Ensure that this is undertaken at a suitable time. Systems with high availability will use a rollover mechanism which should not result in any downtime.{{% /alert %}} + +## Application Server + +### Prerequisites + +#### Certificate Requirements + +A new, valid X.509 certificate needs to be obtained to update the certificates. + +The certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt](), and must meet the following requirements: + +* Subject field must be in one of the following formats depending on whether a multi-domain or wildcard certificate is used: + * Multi-domain certificate - If using the gobetween load balancer this should be specified as the FQDN of the load balancer server (e.g. `CN=load-balancer.domain.com`). If using a different load balancer this must be specified as the FQDN of one of the application servers (e.g. `CN=application-server.domain.com`) + * Wildcard certificate - wildcard format, pertaining to the domain of the Application Servers (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. Additionally if using a multi-domain certificate: + * The FQDN, NetBIOS Name and IP address of all application servers must be added. + * Optionally, the FQDN, NetBIOS Name and IP address of the web application server must be added if the same certificate is used for the web application server. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +This file should be placed in a known location on the Application Server where the certificate update script will be run. This location will be required when running the update script. + +If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject parameter can also be the FQDN of the load balancer (e.g. `CN=load-balancer.domain.com`). + +### Configure Update Certificates Script + +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Update.Certificates.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="Multiple Servers with HA" >}} +.\Cortex.Update.Certificates.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword "#_173143083161001!153134111116076231173085078170111~219102086228187!128017006016134019248042194172107#" ` + -ClientCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ClientCertificatePassword "#_173143083161001!153134111116076231173085078170111~219102086228187!128017006016134019248042194172107#" ` + -Credential $Credential + {{< /tab >}} + {{< tab header="Single Server without HA" >}} +.\Cortex.Update.Certificates.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword "#_173143083161001!153134111116076231173085078170111~219102086228187!128017006016134019248042194172107#" ` + -SkipLoadBalancer ` + -Credential $Credential + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`ServerCertificatePath` | The local path of a new, valid .PFX certificate file on the server. Environment variables cannot be used.

The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the single node cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ClientCertificatePath` | The local path of a .PFX certificate file on the first Application Server in the `ApplicationServerIPv4Addresses` list. This can be the same certificate as the `ServerCertificatePath`. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the load balancer and the nodes on the Application Servers.
| + |`ClientCertificatePassword` | The password for the .PFX certificate file specified in `ClientCertificatePath`.

This is only needed if using the Built-In Load Balancer. {{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`SkipLoadBalancer` | Updates certificates without updating a load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + +### Test Update Certificates Script + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Test `Cortex.Innovation.Update.Certificates.ps1` by running the following command: + + ```powershell + .\Cortex.Innovation.Update.Certificates.ps1 -WhatIf + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the command to finish. It will display the output of the certificate update command without making any changes to the system. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them. + + If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

If this does not work, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. The `WhatIf` script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with `-WhatIf` (e.g. `Cortex.Innovation.Install.Config-WhatIf.json`). This file can be provided when obtaining support. + +### Run Update Certificates Script + +1. Update the certificates for the Application Services and the required infrastructure by running the following command (`Tee-Object` will write output to both the PowerShell console and a log file, the `FilePath` value can be changed if required): + + ```powershell + .\Cortex.Innovation.Update.Certificates.ps1 | Tee-Object -FilePath "cortex-app-certificate-update-log.txt" + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation. + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Installation][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +### Check Application Services + +1. Log on to the server. +1. Import the certificate, used in the `ServerCertificatePath` parameter of the [Configure Update Certificates Script][] section, to your `Current User` certificate store. This can be achieved by double clicking on the certificate .PFX file and following the wizard. + +1. Open a web browser. +1. Navigate to `https://server.domain.com:9080/Explorer`, where `server.domain.com` is the fully qualified domain name of the server. Replace `9080` with new `httpGatewayEndpointPort` value if it was changed during configuration. + + The screen should resemble that in the following figure: + {{< figure src="/images/Service Fabric Explorer - Single.png" title="Healthy Service Fabric Explorer Cluster" >}} + + The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. + + If there is still a warning that the certificate is close to expiring, wait a few hours and refresh the page and it should go away. It can take some time for the certificate to rollover. + +## Web Application Server + +If the Web Applications also use an expiring certificate, it will also need to be updated: + +### Import the Certificate + +If using a single server and using the same certificates for both the Application Services and Web Applications, a new certificate will already be installed. Otherwise, follow the following instructions to import the new certificate for use with the Web Applications: + +1. Put the new, valid certificate in `.pfx` format on the Web Application Server. +1. Double click on the certificate file to open the install certificate wizard. +1. Select `Local Machine` then click `Next`. +1. Click `Next`. +1. Enter the Export Password which the certificate was generated with then click `Next`. +1. Select `Place all certificates in the following store`. +1. Click `Browse…`. +1. Select `Personal`, click `OK` then click `Next`. +1. Click `Finish`. + +### Apply the Certificate + +1. Open Internet Information Services (IIS) Manager. +1. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node. +1. Right-click on the Site node (usually `Cortex`) which contains Gateway. +1. Click `Edit Bindings...` +1. Click on the `https` binding and click `Edit...`. +1. Click the SSL Certificate `Select...` button and select the new certificate from the table. Click `OK` to close the dialog. +1. Click `OK` to close Edit Bindings dialog. +1. Click `Close` to close the Bindings dialog. +1. Open Gateway in a browser. Click the padlock icon next to the URL. The certificate displayed should be the updated one. + +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.CertificateRequirements" >}} +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} +[Configure Update Certificates Script]: {{< ref "#configure-update-certificates-script" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} \ No newline at end of file diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/self-signed-certificates.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/self-signed-certificates.md new file mode 100644 index 000000000..8c0c6d21c --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/self-signed-certificates.md @@ -0,0 +1,236 @@ +--- +title: "Create Self-Signed Certificates" +linkTitle: "Create Self-Signed Certificates" +description: "Information about creating and installing self-signed certificates." +--- + +# {{% param title %}} + +Self-signed certificates should be generated using OpenSSL which is bundled in the {{% ctx %}} Web App Server Install Scripts: + +## Setup OpenSSL in PowerShell + +1. Open a Windows PowerShell (x64) window as administrator. +1. Make a directory in which to store the certificates by running the following command, changing the path as required: + + ```powershell + mkdir C:\Certificates + ``` + +1. Navigate PowerShell to inside the certificates folder created above, using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Certificates" + ``` + +1. Temporarily add OpenSSL to the Path environment variable of your system by running the following command, modifying the path according to the location of `openssl.exe` in the installation scripts on the machine: + + ```powershell + $env:PATH += ";C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts\OpenSSL" + ``` + +## Generate the Root CA Certificate + +1. Create the Root CA private key by running the following command: + + ```powershell + openssl genrsa -out cortexCA.key 4096 + ``` + +1. Generate the Root CA certificate signed with the private key: + 1. Copy the following text into a text editor: + + ```shell + RANDFILE = .rnd + [ ca ] + default_ca = CA_default # The default ca section + [ CA_default ] + # Directory and file locations. + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + policy = policy_strict + [ policy_strict ] + # The root CA should only sign intermediate certificates that match. + # See the POLICY FORMAT section of `man ca`. + countryName = match + stateOrProvinceName = match + organizationName = match + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + [ req ] + # Options for the `req` tool (`man req`). + default_bits = 2048 + distinguished_name = req_distinguished_name + string_mask = utf8only + + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + # Extension to add when the -x509 option is used. + x509_extensions = v3_ca + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_min = 2 + countryName_max = 2 + stateOrProvinceName = State or Province Name (full name) + localityName = Locality Name (eg, city) + 0.organizationName = Organization Name (eg, company) + organizationalUnitName = Organizational Unit Name (eg, section) + commonName = Common Name (eg, your website's domain name) + commonName_max = 64 + emailAddress = Email Address + emailAddress_max = 40 + # Optionally, specify some defaults. + countryName_default = GB + stateOrProvinceName_default = Hampshire + localityName_default = Southampton + 0.organizationName_default = Cortex Ltd + organizationalUnitName_default = We Are CORTEX + commonName_default = Cortex CA + emailAddress_default = Hello@WeAreCORTEX.com + [ v3_ca ] + # Extensions for a typical CA (`man x509v3_config`). + subjectKeyIdentifier = hash + authorityKeyIdentifier = keyid:always,issuer + basicConstraints = critical, CA:true + keyUsage = critical, digitalSignature, cRLSign, keyCertSign + ``` + + 1. Save the file as `ca.cnf` in the directory created for the certificates above. + 1. In the PowerShell window, run the following command: + + ```powershell + openssl req -sha256 -x509 -new -nodes -key cortexCA.key -days 3650 -out cortexCA.pem -config ca.cnf + ``` + + 1. Press `Enter` for all parameters except the Common Name. For this enter `Cortex CA`. + +1. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command: + + ```powershell + openssl pkcs12 -export -inkey cortexCA.key -in cortexCA.pem -out cortexCA.pfx + ``` + +1. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr. +1. Double click on the `cortexCA.pfx` file in the certificates folder to import the certificate into the Windows Certificate Store. Perform the following steps: + 1. Select `Local Machine` then click `Next`. + 1. Click `Next`. + 1. Enter the Export Password which the certificate was generated with then click `Next`. + 1. Select `Place all certificates in the following store`. + 1. Click `Browse…`. + 1. Select `Trusted Root Certification Authorities`, click `OK` then click `Next`. + 1. Click `Finish`. + +## Generate the Certificate + +1. Create a private key for the SSL cert by running the following command: + + ```powershell + openssl genrsa -out cortex.key 2048 + ``` + +1. Generate the SSL certificate request: + 1. Copy the following text into a text editor: + + ```shell + RANDFILE = .rnd + [ ca ] + default_ca = CA_default # The default ca section + [ CA_default ] + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + policy = policy_loose + [ policy_loose ] + # Allow the intermediate CA to sign a more diverse range of certificates. + # See the POLICY FORMAT section of the `ca` man page. + countryName = optional + stateOrProvinceName = optional + localityName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + [ req ] + # Options for the `req` tool (`man req`). + default_bits = 2048 + distinguished_name = req_distinguished_name + string_mask = utf8only + # SHA-1 is deprecated, so use SHA-2 instead. + default_md = sha256 + # Extension to add when the -x509 option is used. + x509_extensions = v3_req + req_extensions = v3_req + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_min = 2 + countryName_max = 2 + stateOrProvinceName = State or Province Name (full name) + localityName = Locality Name (eg, city) + 0.organizationName = Organization Name (eg, company) + organizationalUnitName = Organizational Unit Name (eg, section) + commonName = Common Name (eg, your website's domain name) + commonName_max = 64 + emailAddress = Email Address + emailAddress_max = 40 + # Optionally, specify some defaults. + countryName_default = GB + stateOrProvinceName_default = Hampshire + localityName_default = Southampton + 0.organizationName_default = Cortex Ltd + organizationalUnitName_default = We Are CORTEX + commonName_default = CortexServerCertificate + emailAddress_default = Hello@WeAreCORTEX.com + [ v3_req ] + basicConstraints = CA:FALSE + keyUsage = nonRepudiation, digitalSignature, keyEncipherment + subjectAltName = @alt_names + [ alt_names ] + # Specify all DNS and/or IP addresses that clients can use to access the secured resource. + DNS.1 = MACHINE-NAME + DNS.2 = FULLY QUALIFIED MACHINE NAME / WILDCARD DOMAIN NAME + DNS.3 = localhost + IP.1 = IP ADDRESS + IP.2 = 127.0.0.1 + ``` + + 1. Modify the section `[alt_names]` to include all the required DNS names and IP addresses that clients can use to access the secured resource. + Each DNS name or IP address entry must be suffixed with `.N` where `N` is the unique index of the DNS name or IP address entry; see below for examples: + | Resource URL | Configuration to add | + |---------------------------------------|-----------------------------------| + | `https://wearecortex.com/gateway` | `DNS.1 = wearecortex.com` | + | `https://internal.wearecortex.com/gateway` | `DNS.2 = internal.wearecortex.com`
`or`
`DNS.2 = *.wearecortex.com` | + | `https://10.0.0.0/gateway` | `IP.1 = 10.0.0.0` | + | `https://192.168.1.100/gateway` | `IP.2 = 192.168.1.100` | + + 1. Save the file as `san.cnf` in the directory created for the certificates above. + 1. In the PowerShell window, run the following command: + + ```powershell + openssl req -new -sha256 -key cortex.key -out cortex.req -extensions v3_req -config san.cnf + ``` + + 1. Press `Enter` for everything. The Common Name must stay as `CortexServerCertificate`. + 1. Sign the request with a previously generated Root CA by running the following command: + + ```powershell + openssl x509 -req -sha256 -in cortex.req -CA cortexCA.pem -CAkey cortexCA.key -CAcreateserial -out cortex.pem -days 3650 -extensions v3_req -extfile san.cnf + ``` + + 1. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command: + + ```powershell + openssl pkcs12 -export -inkey cortex.key -in cortex.pem -out cortex.pfx + ``` + + 1. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr. + +## Import the Certificate + +1. Double click on the `cortex.pfx` file in the certificates folder to get the certificate imported to the Windows Certificate Store. Perform the following steps: + 1. Select `Local Machine` then click `Next`. + 1. Click `Next`. + 1. Enter the Export Password which the certificate was generated with then click `Next`. + 1. Select `Place all certificates in the following store`. + 1. Click `Browse…`. + 1. Select `Personal`, click `OK` then click `Next`. + 1. Click `Finish`. diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/ssl-best-practices.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/ssl-best-practices.md new file mode 100644 index 000000000..606c2a379 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/advanced/ssl-best-practices.md @@ -0,0 +1,9 @@ +--- +title: "SSL Best Practices" +linkTitle: "SSL Best Practices" +description: "Information about the recommended security settings for Innovation servers." +--- + +# {{% param title %}} + +{{< section "/advanced/ssl-best-practices.md" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/_index.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/_index.md new file mode 100644 index 000000000..8ada35ca1 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/_index.md @@ -0,0 +1,12 @@ +--- +title: "Multiple Server - With HA (Recommended)" +linkTitle: "Multiple Server - With HA" +description: "Information about installing {{% ctx %}} Innovation across multiple on-premise servers with high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions." +weight: 10 +--- + +{{% pageinfo %}} +Multiple server installations with HA are recommended for the following scenarios: + +* Production installations that are required to scale and support HA +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/architecture.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/architecture.md new file mode 100644 index 000000000..ca58543b5 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/architecture.md @@ -0,0 +1,30 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended Innovation platform architecture, including component descriptions." +weight: 10 +--- + +# {{< param title >}} + +## Components + +{{< section "/architecture/components/multi-server.md" >}} + +## Recommended Architecture + +The following architecture requires 5 servers: + +* 1x Web Application Server which contains Gateway and the Debug Node +* 1x Load Balancer Server +* 3x Application Servers + +{{< figure src="/images/editable/Cortex Innovation Overview.png" class="centre" title="5 Server Architecture Diagram" >}} + +{{< section "/architecture/components/node-details.md" >}} + +## Next Steps? + +1. [Prerequisites][] + +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.Prerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-application-and-loadbalancer-servers.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-application-and-loadbalancer-servers.md new file mode 100644 index 000000000..257e57d0b --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-application-and-loadbalancer-servers.md @@ -0,0 +1,334 @@ +--- +title: "Install Application Servers and Load Balancer" +linkTitle: "Install Application Servers and Load Balancer" +description: "Information about installing the Application Servers and Load Balancer Server." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to install the Application Servers and Load Balancer Server. Please ensure that the [Prerequisites for installing Innovation][] have been read before starting this installation. + +## Make Installation Artefacts Available + +1. Choose one of the Application Servers to be used for installation, and copy the following artefacts to a folder on it: + * Cortex Innovation {{< version >}} - App Server Install Scripts.zip + * Cortex Innovation {{< version >}} - App Services.zip + * Cortex Innovation {{< version >}} - Block Packages.zip + +1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name. + +## Install Microsoft .NET Framework 4.7.2 + +Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.2 to be installed on each Application Server. + +To find the version of the framework that is installed: + +1. On the Start menu, choose `Run`. +1. In the open box, enter `regedit.exe`. You must have administrative credentials to run regedit.exe. +1. In the Registry Editor, open the subkey `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full`. +1. If the `Full` subkey is not present, then you do not have the .NET Framework 4.5 or later installed. +1. Check for a `DWORD` value named `Release`. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is `461808` or over then at least .NET Framework 4.7.2 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it. + +To install .NET Framework 4.7.2: + +1. Download the [.NET Framework 4.7.2][NET Framework 472] installer. +1. Double-click on the installer file to run it. +1. Follow the wizard to complete the installation. + +## Apply Recommended Security Measures + +These are non-compulsory security measures, recommended to be applied to Application Servers and the Load Balancer Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. + +Applying these measures may impact other applications running on your servers. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes. + +### Only Use Recommended Encryption Algorithms and TLS Protocols + +A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at [SSL Best Practices][]. + +{{% alert type="warning" title="Warning" %}}Disabling specific TLS versions or specific Cipher Suites can have impact on {{% ctx %}} components themselves as well as their communication capabilities with third party systems and services, e.g. Execution Service executing flows with blocks which communicate with 3rd parties via PowerShell or REST. All parties communicating together must support a shared protocol version and cipher suite, otherwise they will not be able to establish a secure communication link between each other.{{% /alert %}} + +The settings can be applied by running a script. Be aware that each server will be restarted when the script is run. Apply the settings by following these instructions: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + + {{% alert title="Note" %}} +To avoid answering all of the prompts `-Override 0` can be added to the end of the script. This will automatically apply all settings and forcibly restart the servers. + {{% /alert %}} + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press `OK`. + + If `-Override 0` has been specified no further steps need to be taken and you can move on to the next section when the servers have restarted. +1. To use all the recommended settings click `Apply all` to each `Apply Cortex recommended security best practices` prompt. + + To selectively apply each setting select `Choose which to apply`. Each change will then be prompted with a Yes/No confirmation before applying. This will need to be done for each server. +1. Restart each machine when the script asks. The current machine will be restarted last, the PowerShell script will close at this time. + +## Add Antivirus Exclusions + +If Windows Defender is not running on the Application Servers, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on each of the Application Servers and continue to the next section, otherwise follow these steps: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Add.WindowsDefenderExclusions.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK. +1. A message will indicate that the script has completed successfully. + +## Check Port Usage + +To check all necessary ports are free, follow these steps: + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Run the `Cortex.Innovation.Test.PortUsage.ps1` script using the following command, modifying the `ApplicationServers` value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the `LoadBalancerServer` value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the `LoadBalancerServer` parameter if using an [alternative load balancer][]): + + ```powershell + .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server" + ``` + +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK. + +1. If all ports are free, the script will report the following for each Application Server: + + `All ports required by Cortex Innovation are free` + + If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the `Cortex.Innovation.Install.Config.json` configuration file, in the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, to use different ports. This will be used later during installation. + + The `Cortex.Innovation.Test.PortUsage.ps1` script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free. + +## Configure Installation Script + +1. In the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.ps1` script and open it with a text editor. +1. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below: + + {{< tabpane lang="powershell" >}} + {{< tab header="CA Certs, Built-in Load Balancer">}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -ClientCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ClientCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs, Built-in Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -LoadBalancerServerIPv4Address "192.168.1.4" ` + -UseSelfSignedCertificates ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="CA Certs, Alternative Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -ServerCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ServerCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -ClientCertificatePath "C:\Install\Certificates\cert.pfx" ` + -ClientCertificatePassword '#_186224203199039!168155035100255155162114088105027~037077176064169!055142133197216213014226219148063#' ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< tab header="Self-Signed Certs, Alternative Load Balancer" >}} +.\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json ` + -AppServicesPath "C:\Install\Cortex Innovation {{< version >}} - App Services.zip" ` + -BlockPackagesPath "C:\Install\Cortex Innovation {{< version >}} - Block Packages.zip" ` + -ApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -CustomerName "Customer1" ` + -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") ` + -UseSelfSignedCertificates ` + -SkipLoadBalancer ` + -Credential $Credential ` + -LdapConnectionDetails @{ + Host= "LDAP://ldapserver.fqdn.com:389" + UseSsl= $false + Username= "someUserName" + Password= '#_156218162004047!225018081008117174092221250099053~110194001237006!035122107175168133055021013201167#' + } ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt" + {{< /tab >}} + {{< /tabpane >}} + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |----------------------------------------------|-------------| + |`AppServicesPath` | Configure this value with the location of the Application Services zip file on the Application Server used for installation. | + |`BlockPackagesPath` | Configure this value with the location of the Block Packages zip file on the Application Server used for installation. | + |`ApiGatewayBasicAuthUsername` | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.

For security reasons it is recommended that the default value `BasicAuthUser` should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].

This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ApiGatewayBasicAuthPassword` | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.

For security reasons it is recommended that the default value should be changed.

This value will be needed later, [when installing Gateway][Install Gateway].{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`CustomerName` | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. | + |`ApplicationServerIPv4Addresses` | The IPv4 addresses of the Application Servers. The first of these must be the Application Server used for installation. | + |`LoadBalancerServerIPv4Address` | The IPv4 address of the Load Balancer Server. This is only needed if using the built-in load balancer. | + |`ServerCertificatePath` | The local path of a .PFX certificate file on the first Application Server in the `ApplicationServerIPv4Addresses` list. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the Application Services.
  • Allowing Application Services to identify themselves to clients such as Gateway.
  • Preventing unauthorised nodes from joining the HA cluster.
  • Connecting to Service Fabric Explorer from each of the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}| + |`ServerCertificatePassword` | The password for the .PFX certificate file specified in `ServerCertificatePath`.

This is only needed if installing with CA Certificates (Recommended).{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`ClientCertificatePath` | The local path of a .PFX certificate file on the first Application Server in the `ApplicationServerIPv4Addresses` list. This can be the same certificate as the `ServerCertificatePath`. Environment variables cannot be used.

This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the [Certificate Requirements][].

This certificate will be used for:
  • Securing communication between the load balancer and the nodes on the Application Servers.
{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + |`ClientCertificatePassword` | The password for the .PFX certificate file specified in `ClientCertificatePath`.

This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`UseSelfSignedCertificates` | Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

Not recommended for production use. | + |`SkipLoadBalancer` | Installs Application Services and required infrastructure without installing a load balancer. Use when using an alternative load balancer or no load balancer. | + |`Credential` | The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

This does not need to be changed, a prompt will appear to enter this information when the script is run. | + |`LdapConnectionDetails` | The connection details to the LDAP server.

This must be configured with a valid `Host`, `Username`, `Password`, and whether the LDAP server uses SSL using `UseSsl`. {{< alert type="note" title="Note" >}}The parameters `Host` and `Username` should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}. The parameter `Password` must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}} | + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + + The `ApiGatewayBasicAuthUsername` and `ApiGatewayBasicAuthPassword` will be needed later, [when installing Gateway][Install Gateway]. + + {{% alert title="Note" %}} +More advanced configuration (such as changing ports) can be undertaken by modifying the `Cortex.Innovation.Install.Config.json` file but this shouldn't be required for most installations. More information about this can be found at {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.AdvancedConfigMultipleServer" title="Advanced Application Server and Load Balancer Configuration Changes" >}}. + {{% /alert %}} + +1. Save and close `Cortex.Innovation.Install.ps1`. + +## Test Installation Script + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 -WhatIf + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -WhatIf -AcceptEULA + ``` + +1. Run the PowerShell command to test the installation script. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. +1. Wait for the command to finish. It will display the output of the installation command without making any changes to the system, to ensure things like communication between the servers are working. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them. + + If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

If this does not work, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. The `WhatIf` script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with `-WhatIf` (e.g. `Cortex.Innovation.Install.Config-WhatIf.json`). This file can be provided when obtaining support. + +## Run Installation Script + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install HA Services and the required infrastructure. +1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK. +1. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from [{{% ctx %}} Service Portal][CORTEX Service Portal]. Press OK. +1. Wait for the script to finish running. This should take approximately 10 minutes. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation. + + In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command: + + ```powershell + .\Cortex.Innovation.Uninstall.ps1 + ``` + + If the errors do not give any instructions on how to rectify, see [Troubleshooting During Installation][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance. + +## Check Application Services + +{{< section "/install-application-server/multi-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Install Web Application Server][] + +[alternative load balancer]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AltLoadBalancer" >}} +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AntivirusExclusions" >}} +[Certificate Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.CertificateRequirements" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.EncryptionRequirements" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Install Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[Install Web Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.InstallWebApplicationServer" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Prerequisites for installing Innovation]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.Prerequisites" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/_index.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/_index.md new file mode 100644 index 000000000..a2bf8bace --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/_index.md @@ -0,0 +1,10 @@ +--- +title: "Install the Web Application Server" +linkTitle: "Install Web Application Server" +description: "Information about installing the Web Application Server." +weight: 40 +--- + +This guide describes how to install the Web Application Server. Please ensure that [Install Application Servers and Load Balancer][] has been completed before starting this installation. + +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md new file mode 100644 index 000000000..e200454ac --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-debugger-installation.md @@ -0,0 +1,61 @@ +--- +title: "Install Flow Debugger" +linkTitle: "Install Flow Debugger" +description: "Information about installing the Flow Debugger." +weight: 20 +--- + +# {{% param title %}} + +This guide describes how to install the Flow Debugger on the Web Application Server. Please ensure that the [web application server prerequisites][] have been completed before starting this installation. + +{{% alert title="Important" color="warning" %}} +{{< ctx >}} Gateway requires a local instance of the Application Server components to enable the debugging of flows. +{{% /alert %}} + +## Install Microsoft .NET Framework 4.7.2 + +{{< section "/install-application-server/install-dot-net-framework.md">}} + +## Add Antivirus Exclusions + +If Windows Defender is not running on the server, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps: + +{{< section "/install-application-server/single-server/add-antivirus-exclusions.md">}} + +## Check Port Usage + +{{< section "/install-application-server/single-server/check-port-useage.md">}} + +## Configure Installation Script + +{{< section "/install-web-application-server/add-innovation-only/configure-debugger-installation-script.md">}} + +## Test Installation Script + +{{< section "/install-application-server/single-server/test-installation-script.md">}} + +## Run Installation Script + +{{< section "/install-application-server/single-server/run-installation-script.md">}} + +## Add Read and Execute access to Windows Crypto folder + +{{< section "/install-application-server/single-server/add-permissions-to-crypto-folder.md">}} + +## Check Application Services + +{{< section "/install-application-server/single-server/check-application-services.md">}} + +# Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Install Gateway][] + +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AntivirusExclusions" >}} +[Import Root Certificate]: {{< ref path="#import-root-certificate" >}} +[Install Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.GatewayInstallation" >}} +[web application server prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.WebApplicationServerPrerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md new file mode 100644 index 000000000..547e5e1a0 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/perform-gateway-installation.md @@ -0,0 +1,133 @@ +--- +title: "Install Gateway" +linkTitle: "Install Gateway" +description: "Information about installing {{% ctx %}} Gateway." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to install {{% ctx %}} Gateway on the Web Application Server. Please ensure that the [Flow Debugger installation][] has been completed before starting this installation. + +## Perform Gateway Installation + +### Certificate Requirements + +It is possible for {{% ctx %}} Gateway to reuse the certificate used when [installing the Flow Debugger][Flow Debugger installation]; If doing so, you must [Assign a Certificate Friendly Name][Assign Certificate Friendly Name] and set the `ImportCertificate` parameter to `$false` when [configuring the {{% ctx %}} Gateway Installation Script][Install Gateway] to ensure use of the correct certificate and to prevent it from being overwritten. + +### Configure {{% ctx %}} Gateway Installation Script + +1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` + -FeatureFlags "InnovationId" ` + -ServiceFabricApiGatewayEndpoint "https://server.domain.com/" ` + -ServiceFabricUsingSelfSignedCertificates $false ` + -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerEndpoint "https://server.domain.com:8722/api/" ` + -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` + -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $true ` + -CertificateFilePath "C:\Install\Certificate.pfx" ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | + |`FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} Innovation feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Licensing Requirements][], if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will set the `FeatureFlags` value in the Gateway web.config.| + |`ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Load Balancer Server. The port should be specified if it is not the default HTTPS port (443), and there must be a trailing slash, e.g. `https://server.domain.com/` or `https://server.domain.com:8722/`.

This will set the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Servers][Configure Installation Script], `$true` if you used self-signed certificates.

This will set the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`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.

This will set the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Servers][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Web Application Server.

This will set the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Flow Debugger installation]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Flow Debugger installation]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will set the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that should be used to run the {{% ctx %}} Gateway application pool as configured in [Get {{% ctx %}} Gateway Application Pool User][Get CORTEX Gateway Application Pool User].| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | Change this from `$true` to `$false` if you do not require the certificate to be imported as part of the installation process.

Note that if this is changed to `$false` you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation.| + |`CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged but you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation.| + |`CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false` this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created Cortex site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +### Install {{% ctx %}} Gateway + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. +1. A prompt will appear to enter the password for the user specified to run the {{% ctx %}} Gateway Application Pool. This should be entered, and then hit `Enter`. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. + +### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Setup Gateway][] + +[Assign Certificate Friendly Name]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AssignCertificateFriendlyNameNew" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScript" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Flow Debugger installation]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.DebuggerInstallation" >}} +[Get CORTEX Gateway Application Pool User]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.GetGatewayAppPoolUser" >}} +[Import Certificate Manually]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ImportCertificateManuallyNew" >}} +[Import Root Certificate]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ImportRootCertificate" >}} +[Install Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.LicensingRequirements" >}} +[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.SetupGateway" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/prerequisites.md new file mode 100644 index 000000000..27525eb10 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/install-web-application-server/prerequisites.md @@ -0,0 +1,104 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about performing the prerequisities for the Web Application Server." +weight: 10 +--- + +# {{% param title %}} + +This guide describes how to install the Web Application Server. Please ensure that [Install Application Servers and Load Balancer][] has been completed before starting this installation. + +## Make Installation Artefacts Available + +{{% alert title="Note" %}} +We recommend that the single-node Service Fabric instance, used by {{% ctx %}} Gateway as a Debugger instance, and {{% ctx %}} Gateway are installed on the same Web Application Server. +{{% /alert %}} + +{{< section "/install-web-application-server/make-installation-artefacts-available.md">}} + +## Licensing + +{{< section "/install-web-application-server/add-innovation-only/licensing.md">}} + +## Get {{% ctx %}} Gateway Application Pool User + +A domain user account is required for the {{% ctx %}} Gateway application pool and must be created prior to performing the installation below. + +In line with best practices, this account should not be given administrator rights, nor should it be used for any purposes other than those specified for {{% ctx %}} Gateway. + +## Grant folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/grant-gateway-user-folder-permissions.md">}} + +## Certificate Requirements + +The Flow Debugger and {{% ctx %}} Gateway require an X.509 SSL certificate to be installed on the Web Application Server. +
+For {{% ctx %}} Gateway, the certificate must have the following properties: + +* Enhanced Key Usage: `Server Authentication` and `Client Authentication` +* Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1 + +If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error. +
+For the Flow Debugger, the certificate must have the following properties: + +* Subject field must be in one of the following formats depending on whether a multi-domain or wildcard certificate is used: + * Multi-domain certificate - If using the [gobetween][] load balancer this should be specified as the FQDN of the load balancer server (e.g. `CN=load-balancer.domain.com`). If using a different load balancer this must be specified as the FQDN of one of the application servers (e.g. `CN=application-server.domain.com`) + * Wildcard certificate - wildcard format, pertaining to the domain of the Application Servers (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. Additionally if using a multi-domain certificate: + * The FQDN, NetBIOS Name and IP address of the web application server and all application servers must be added. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +{{% alert title="Important" color="warning" %}} +Multi-domain certificates, wildcard certificates, auto-generated self-signed certificates and {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" title="manually created self-signed certificates" >}} can be used. However, self-signed certificates are not recommended for production instances. +
+It is possible to reuse the Flow Debugger certificate for {{% ctx %}} Gateway; If doing so, you must {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AssignCertificateFriendlyNameNew" title="Assign a Certificate Friendly Name" >}} after the debugger has been installed and set the `ImportCertificate` parameter to `$false` in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" title="Configure CORTEX Gateway Installation Script" >}} to ensure use of the correct certificate and to prevent it from being overwritten. +{{% /alert %}} + +### Import Root Certificate + +{{% alert title="Note" %}}This step is only required if using a self-signed certificate signed by your own Root Certificate e.g. OpenSSL. If this is not the case proceed to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ImportCertificateManuallyNew" title="Import Certificate Manually" >}} {{% /alert %}} + +This step must be carried out prior to the installation otherwise the URL validation will fail. In order to import the Root Certificate, ensure that the file is in a known location on this server and complete the following steps: + +1. Using Windows File Explorer navigate to the location of the Root Certificate file. +1. Double click on the Root Certificate file to import the certificate into the Windows Certificate Store. Perform the following steps: + + 1. Select `Local Machine` then click `Next`. + 1. Click `Next`. + 1. Enter the Export Password which the certificate was generated with then click `Next`. + 1. Select `Place all certificates in the following store`. + 1. Click `Browse…`. + 1. Select `Trusted Root Certification Authorities`, click `OK` then click `Next`. + 1. Click `Finish`. + 1. [Import][Import Certificate Manually] the X.509 SSL certificate. + +### Import Certificate Manually + +{{% alert title="Note" %}}The certificate can be imported automatically by setting the `ImportCertificate` parameter to `$true` in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" title="Configure CORTEX Gateway Installation Script" >}}. If importing the certificate automatically proceed to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.DebuggerInstallation" title="Install Flow Debugger" >}}

If the certificate has previously been imported you must {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.AssignCertificateFriendlyNameNew" title="assign a friendly name" >}}.{{% /alert %}} + +To import the certificate manually follow the below steps: + +1. Locate the certificate file on the machine and right-click on the file. +1. Select `Install Certificate`. +1. Follow the Wizard and when prompted, ensure you import it into the `Local Machine` store and not `Current User`. +1. Assign the imported certificate a [friendly name][Assign Certificate Friendly Name]. + +### Assign Certificate Friendly Name + +{{< section "/install-web-application-server/add-innovation-only/assign-certificate-friendly-name.md">}} + +## Next Steps? + +1. [Install Flow Debugger][] + +[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} +[Import Certificate Manually]: {{< ref "#import-certificate-manually" >}} +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} +[Install Flow Debugger]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.DebuggerInstallation" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/prerequisites.md new file mode 100644 index 000000000..bced5c869 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/prerequisites.md @@ -0,0 +1,304 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- + +# {{% param title %}} + +The prerequisites required for each server role (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking installation. + +## Hardware Requirements + +{{% alert title="Note" %}}The recommended number of servers is 5, and allows each server role instance to be installed on its own server.{{% /alert %}} + +| Server Role | Servers Required | CPU Cores (> 2GHz) | RAM (GB) | Disk (GB) | +|------------------|-----------------------|-----------------------------------|---------------|----------------------| +| Load Balancer | 1[^1] | 4+ *Recommended*
2 *Minimum* | 8+ *Recommended*
4 *Minimum* | 50+ *Recommended*
30 *Minimum*
5+ free on installation drive | +| Application Server | 3 *Bronze availability*[^2]
5 *Silver availability*
7 *Gold availability*
9 *Platinum availability* | 4+ *Recommended*
2 *Minimum* | 16+ *Recommended*
8 *Minimum* | 75+ *Recommended*
60 *Minimum*
40+ free on %ProgramData% drive | +| Web Application Server | 1 | 4+ *Recommended*
2 *Minimum* | 16+ *Recommended*
12 *Minimum* | 150+ *Recommended*
100 *Minimum*
30+ free on installation drive
40+ free on %ProgramData% drive | + +[^1]: A software-based load balancer called [gobetween][] is provided with the platform. This must be installed on its own server as it doesn't support routing traffic to itself. It also doesn't currently support HA, but it may be possible to use multiple gobetween load balancers with Anycast network addressing and routing to provide high availability, as described in [https://en.wikipedia.org/wiki/Anycast][Anycast]; however, this has not been verified yet. It is possible to use an [alternative load balancer][] to the one provided. +[^2]: Application Servers support HA via clustering. A cluster must consist of a minimum of 3 nodes, and the number of nodes must be an odd number to ensure a quorum. Currently only the Bronze availability (3 nodes) is supported. Silver, Gold and Platinum support will be added in future. + +## Software Requirements + +| Server Role | Windows Server[^3] | .Net | PowerShell[^4] | IIS[^5] | Other Software | +|------------------|-------------------------|------|------------|---------|----------| +| Load Balancer | [2022 (x64)][Microsoft Server 2022] *Recommended*
[2019 (x64)][Microsoft Server 2019] | [Framework 4.7.2][NET Framework 472] | 5.1 | | +| Application Server | [2022 (x64)][Microsoft Server 2022] *Recommended*
[2019 (x64)][Microsoft Server 2019] | [Framework 4.7.2][NET Framework 472] | 5.1 | | +| Web Application Server | [2022 (x64)][Microsoft Server 2022] *Recommended*
[2019 (x64)][Microsoft Server 2019] | [Framework 4.7.2][NET Framework 472] | 5.1 | 10.0.20348[^6]
10.0.17763[^7]
[URL Rewrite Module 2.1][IIS Url Rewrite] | [Microsoft Web Deploy 3.0 or later][Web Deploy]
[Visual C++ Redistributable 2013 (x64)][C++ Redistributable] | + +[^3]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. +[^4]: PowerShell 5.1 ships with Windows Server 2019 and 2022. +[^5]: IIS is supported; other web servers, including IIS Express are not supported. +[^6]: Ships as a windows role within Windows Server 2022. +[^7]: Ships as a windows role within Windows Server 2019. + +## Domain Requirements + +All servers must be on the same domain and cannot be domain controllers. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|----------------------------|----------------|----------------|------------------| +| Windows Server 2003 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2003 R2 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2016 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2019 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2022.9 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for all of your servers (Web, Application and Load Balancer). + +## Licensing Requirements + +A valid {{% ctx %}} licence file and {{% ctx %}} Innovation feature identifier must be procured from {{% ctx %}}. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the Web Application server and it should contain fingerprints for the Web Application Server and each Application Server. + +To get a licence file and feature identifier take the following steps: + +1. Copy the following template to a text file: + + ```text + Web Application Server + MachineID: + Fingerprint: + + Application Server 1 + MachineID: + Fingerprint: + + Application Server 2 + MachineID: + Fingerprint: + + Application Server 3 + MachineID: + Fingerprint: + + Please also include a suitable {{% ctx %}} Innovation feature identifier. + ``` + +1. Extract `Cortex Innovation {{< version >}} - Licence Fingerprint Generator.zip`. +1. From that folder, copy `Cortex.Licensing.FingerprintGeneration.exe` to the Web Application server. +1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: WEBAPP-SERVER + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + +1. Copy the output (machine identifier and fingerprint) to the `Web Application Server` section of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server. +1. For each Application Server take the following steps: + 1. Copy `Cortex.Licensing.FingerprintGeneration.exe` to the Application server. + 1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: APP-SERVER1 + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + + 1. Copy the output (machine identifier and fingerprint) to one of the `Application Server` sections of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server. +1. Request a licence and feature identifier by raising a case in the [{{% ctx %}} Service Portal][CORTEX Service Portal], including the contents of the text file containing all of the fingerprint and machine information in the body of the case. +1. When the licence and feature identifier have arrived, copy the file `Cortex.lic` to `%ProgramData%\Cortex\Licences` on the Web Application Server, creating the `Cortex` and `Licences` folders if they don't exist. Save the feature identifier for use when [Installing Gateway][]. + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Filesystem Requirements + +The Web Application Server, each Application Server and [gobetween][] Load Balancer Server (if used) must: + +* use an NTFS filesystem. +* enable Network Discovery and File Sharing + +To enable Network Discovery and File Sharing: +1. Open File Explorer. +2. Click `Network` on the left. +3. A banner similar to the following will appear if Network Discovery and File Sharing is turned off: + {{< figure src="/images/Network Discovery 1.png" title="Network and File Discovery Disabled" >}} +4. Click the banner. +5. Click `Turn on network discovery and file sharing`: + {{< figure src="/images/Network Discovery 2.png" title="Enable Network and File Discovery" >}} + +## Service Requirements + +On the Web Application Server and each Application Server, the following Windows Services must be running: + +* Performance Logs & Alerts +* Remote Registry +* Windows Event Log + +## Security Requirements + +### Installation User + +On all Application Servers, Web Application Server and Load Balancer Server, a domain user, which is a member of the Local Administrators group, must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the HA platform that {{% ctx %}} Innovation is built upon. + +### IIS Application Pool User + +For Gateway, a domain user must be available to run the IIS Application Pool. This user must be given `Log on as a service` and `Log on as a batch job` permissions otherwise the Application Pool will not be able to run. Information about how to do this will be given during installation. + +### Antivirus Exclusions + +It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the Web Application Server and each Application Server to reduce antivirus processing on Service Fabric artefacts: + +Folder Exclusions: + +* %ProgramFiles%\Microsoft Service Fabric +* %ProgramData%\SF +* %ProgramData%\SF\Logs + +Process Exclusions: + +* Fabric.exe +* FabricHost.exe +* FabricInstallerService.exe +* FabricSetup.exe +* FabricDeployer.exe +* ImageBuilder.exe +* FabricGateway.exe +* FabricDCA.exe +* FabricFAS.exe +* FabricUOS.exe +* FabricRM.exe +* FileStoreService.exe + +If you are using a built-in load balancer, it is advised that the following antivirus exclusions are created on the Load Balancer Server to reduce antivirus processing on service health checks: + +Process Exclusions: + +* gobetween.exe +* Cortex.Installation.HealthCheck.exe + +A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually. + +If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist. + +### Port Requirements + +{{% ctx %}} Innovation and Microsoft Service Fabric require a range of [firewall ports to be opened][Port Requirements] between the servers and specific services. + +If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in [Port Requirements][] to open the correct ports. + +The `Cortex.Innovation.Test.PortUsage.ps1` script is provided during installation to test the ports on the Web Application Server and each Application Server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible. + +### Certificate Requirements + +{{< alert title="Important" color="warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + +#### Application Servers + +{{% alert title="Note" %}} +For production systems it is recommended that X.509 SSL multi-domain or wildcard certificates are obtained from a Certificate Authority and used for installation. For non-production systems, certificates can be omitted from installation and it will create and use self-signed certificates. This may prevent 3rd parties that require valid certificate verification to access the API Gateway Service. +{{% / alert %}} + +An X.509 SSL multi-domain or wildcard certificate should be used to: + +* Secure communication between the load balancer and the nodes on the Application Servers. +* Secure communication between the Application Services. +* Allow Application Services to identify themselves to clients such as Gateway. +* Prevent unauthorised nodes from joining the HA cluster. +* Connect to Service Fabric Explorer from each of the Application Servers. + +The certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt](), and must meet the following requirements: + +* Subject field must be in one of the following formats depending on whether a multi-domain or wildcard certificate is used: + * Multi-domain certificate - If using the [gobetween][] load balancer this should be specified as the FQDN of the load balancer server (e.g. `CN=load-balancer.domain.com`). If using a different load balancer this must be specified as the FQDN of one of the application servers (e.g. `CN=application-server.domain.com`) + * Wildcard certificate - wildcard format, pertaining to the domain of the Application Servers (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. Additionally if using a multi-domain certificate: + * The FQDN, NetBIOS Name and IP address of all application servers must be added. + * Optionally, the FQDN, NetBIOS Name and IP address of the web application server must be added if the same certificate will be used for the [web application server][]. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +This file should be placed in a known location on the Application Server where the installation scripts will be run. This location will be required when running the installation script. + +If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject field can also be the FQDN of the load balancer (e.g. `CN=load-balancer.domain.com`). + +#### Web Application Server + +{{% ctx %}} Gateway requires an X.509 SSL certificate to be installed on the Web Application Server. This can be the same certificate as used for the application servers or a different certificate. + +The certificate must have the following properties: + +* Enhanced Key Usage: `Server Authentication` and `Client Authentication` +* Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1 + +If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error. + +{{% alert title="Important" color="warning" %}} +Multi-domain certificates, wildcard certificates, auto-generated self-signed certificates and {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" title="manually created self-signed certificates" >}} can be used. However, self-signed certificates are not recommended for production instances. +{{% /alert %}} + +More information about importing the certificate is given during installation. + +### TLS Requirements + +There is a set of non-compulsory security measures, recommended to be applied to the Web Application Server and each Application Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following: + +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + +See [SSL Best Practices][] for a full list of the security changes which will be applied. + +A script is provided during installation to apply these security changes: + +* For the Application servers: `Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1` +* For the Web Application Server: `Cortex.Innovation.Install.SSLBestPractices.ps1` + +### Encryption Requirements + +{{< section "/prerequisites/install-innovation-only/multi-server/encryption-requirements.md">}} + +## Alternative Load Balancer Requirements + +Innovation has a [gobetween][] load balancer included that isn't highly available; It is possible to use an alternative. The requirements for installing an alternative load balancer are as follows: + +* Must support a round robin (or similar) method of load balancing to specified ports on 3 nodes. +* Must be able to health check each node by running a predefined batch script (`ApiGatewayTypeHealthcheck.bat`, which resides in the `gobetween` folder of the `Cortex Innovation {{< version >}} - App Server Install Scripts`) that returns 1 for healthy and 0 for unhealthy. +* Must be able to access each of the Application Servers via HTTPS. +* Ideally it should support UDP to use the SNMP functionality of the [Triggers Service][TriggersService]. +* Ideally it should be highly available to avoid a single point of failure in the system. + +## Next Steps? + +1. [Install Application Servers and Load Balancer][] + +[alternative load balancer]: {{< ref "#alternative-load-balancer-requirements" >}} +[Anycast]: {{< url path="Anycast.MainDoc" >}} +[Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.Architecture" >}} +[C++ Redistributable]: {{< url path="MSDownload.CPlusPlusRedistributable.2013" >}} +[Create Self-Signed Certificates]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[gobetween]: {{< url path="GoBetween.MainDoc" >}} +[IIS Url Rewrite]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} +[Install Application Servers and Load Balancer]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.InstallApplicationAndLoadBalancerServers" >}} +[Installing Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureCortexGatewayInstallationScriptNew" >}} +[Microsoft Server 2019]: {{< url path="MSEval.WindowsServer.2019" >}} +[Microsoft Server 2022]: {{< url path="MSEval.WindowsServer.2022" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Port Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.PortRequirements" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[TriggersService]: {{< url path="Cortex.Guides.CortexInnovation.CoreApplication.Services.TriggersService.MainDoc" >}} +[web application server]: {{< ref "#web-application-server" >}} +[Web Deploy]: {{< url path="MSDownload.WebDeploy" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/setup-gateway.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/setup-gateway.md new file mode 100644 index 000000000..be52563aa --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/setup-gateway.md @@ -0,0 +1,84 @@ +--- +title: "Setup Gateway" +linkTitle: "Setup Gateway" +description: "Information about setting up {{% ctx %}} Gateway for first-time use." +weight: 50 +--- + +# {{% param title %}} + +This guide describes how to setup Gateway. Please ensure that the [Gateway Installation][] has been completed before taking these steps. + +## Gateway Initial Setup + +Log on to Gateway and run through the setup wizard: + +1. Open a [supported web browser][] and navigate to `://:/`, e.g. `https://server.domain.com/gateway`. + + If an error message is displayed in the browser, wait a few minutes and refresh the page as it is possible that the website was still starting. +1. Log on using the default credentials that Gateway deploys with: + + Username: `administrator` + + Password: `Adm1n1strat0r` +1. On a newly installed system, you will be presented with a Setup Wizard at this point, which will guide you through some basic configuration steps: + * [Account Details] + * [LDAP Connection] + * [LDAP Authorisation] +1. Follow the steps in the setup wizard to configure the relevant areas: + + ### Account Details + + 1. Click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup1.png" title="Initial Setup Screen" >}} + 1. Enter an email address for the Administrator and click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup2.png" title="Administrator Details Screen" >}} + 1. Change the Administrator password to a unique, secret password and click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup3.png" title="Change Password Screen" >}} + + ### LDAP Connection + + 1. Enter the details of your Active Directory server and provide a Username and Password for a user with read access to it: + + A connection to an Active Directory server must be established in order to assign authorisation rights to users. + 1. In the `Server` field, enter the Hostname, FQDN or IP Address of the Active Directory server that Gateway should use to authenticate and authorise users. + 1. In the `Port` field, enter the port number of the Active Directory server. The well-known port for LDAP traffic is `389`; if SSL encryption is used, the well-known port is `636`. + 1. If an SSL connection is to be used, tick the box `Use SSL`. + 1. In the `Username` field, enter a valid username of a user that has read permissions for the Active Directory server. + 1. In the `Password` field, enter the password of the user entered in the previous step. + 1. To reduce the scope of any Active Directory searches, add one or more base DNs (Distinguished Names). For each base DN click `Add` and enter the full LDAP path e.g `CN=group, OU=organisational unit, DC=domain, DC=com`. These will be used as the roots of any Active Directory searches performed. For more information about distinguished names see . + 1. Click `Test Connection` to validate the connection and the user credentials entered and click `Next Step`. + + {{< figure class="centre" src="/images/Gateway Setup4.png" title="LDAP Connection Screen" >}} + + ### LDAP Authorisation + + 1. If the authorisation grid fails to load first time round, click `Retry`. + 1. Assign access permissions to Active Directory groups: + + To allow users to access the various roles within Gateway, it is first necessary to assign them the appropriate access rights. + Gateway currently supports four roles, but only two are relevant for {{% ctx %}} Innovation: + + * Admin + * Studio + + To give a user access to a role, set access for a group or Organisational Unit (OU) that the user is a member of: + + 1. Expand the groups or OUs, or search for the group or OU, to be assigned one or more roles. + 1. Check the relevant roles for each group. Checking a parent group will cascade the setting to all child groups. + + {{< figure class="centre" src="/images/Gateway Setup5.png" title="LDAP Authorisation Screen" >}} + + 1. Click `Complete Setup` to commit the changes. + 1. To test the permissions, log out as Administrator and then log in as a user with `Studio` permissions. + +## Next Steps? + +1. [Try it out][] + +[Account Details]: {{< ref "#account-details" >}} +[Gateway Installation]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.GatewayInstallation" >}} +[LDAP Authorisation]: {{< ref "#ldap-authorisation" >}} +[LDAP Connection]: {{< ref "#ldap-connection" >}} +[supported web browser]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.WebBrowserRequirements" >}} +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/try-it-out.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/try-it-out.md new file mode 100644 index 000000000..cbebbb92d --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/multiple-server-with-ha/try-it-out.md @@ -0,0 +1,66 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} Innovation for the first time." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. + +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Dev` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Activity` 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. 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, 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 Flow` and `End Flow` 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 Variables Grid, set `Is Output Variable?` to `true` for the new `Result` variable. +1. Add a breakpoint to the `End Flow` block and start the flow. An execution token should appear. + If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][Troubleshooting Flow Not Starting]. +1. Select the execution in the Executions Grid (bottom panel). +1. The `Result` variable displayed in the Variables Viewer (right panel) should show the current time. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that either one or more of the parameters prefixed with `Service Fabric` in the `CortexGateway.SetParameters.xml` file was not set properly when installing Gateway, or the Application Services aren't healthy. See [Troubleshooting][Troubleshooting No Publish] for more information. + +## Test Executing Production Flows + +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +1. {{% ctx %}} Innovation has now been verified and is ready to use. + +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.SetupGateway" >}} +[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/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/_index.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/_index.md new file mode 100644 index 000000000..a2e303100 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/_index.md @@ -0,0 +1,12 @@ +--- +title: "Single Server - Without HA" +linkTitle: "Single Server - Without HA" +description: "Information about installing {{% ctx %}} Innovation on a single on-premise server without high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions." +weight: 50 +--- + +{{% pageinfo %}} +Single server installations without HA are not recommended for the following scenarios: + +* Production installations that are required to scale and support HA +{{% /pageinfo %}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/architecture.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/architecture.md new file mode 100644 index 000000000..07d150be4 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/architecture.md @@ -0,0 +1,28 @@ +--- +title: "Architecture" +linkTitle: "Architecture" +description: "Information about the recommended Innovation platform architecture, including component descriptions." +weight: 10 +--- + +# {{% param title %}} + +## Components + +{{< section "/architecture/components/single-server.md" >}} + +## Single Server Architecture + +The following architecture requires 1 server: + +{{< figure src="/images/editable/Cortex Innovation Overview-Single Server.png" class="centre" title="1 Server Architecture Diagram" >}} + +{{< section "/architecture/components/node-details.md" >}} + +{{% alert type="warning" title="Warning" %}} This architecture is not recommended for production platforms that are required to scale and support HA. Additionally, upgrades require application redeployment with downtime rather than using rolling upgrades. {{%/alert %}} + +## Next Steps? + +1. [Prerequisites][] + +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Prerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-application-server.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-application-server.md new file mode 100644 index 000000000..bf347167f --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-application-server.md @@ -0,0 +1,64 @@ +--- +title: "Install Application Server" +linkTitle: "Install Application Server" +description: "Information about installing the Application Server." +weight: 30 +--- + +# {{% param title %}} + +This guide describes how to install the Application Server components on the server. Please ensure that the [Prerequisites][] have been read before starting this installation. + +## Make Installation Artefacts Available + +{{< section "/install-application-server/make-installation-artefacts-available.md">}} + +## Install Microsoft .NET Framework 4.7.2 + +{{< section "/install-application-server/install-dot-net-framework.md">}} + +## Apply Recommended Security Measures + +{{< section "/install-application-server/apply-recommended-security-measures.md">}} + +## Add Antivirus Exclusions + +If Windows Defender is not running on the server, ensure that the [Antivirus Exclusions][] have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps: + +{{< section "/install-application-server/single-server/add-antivirus-exclusions.md">}} + +## Check Port Usage + +{{< section "/install-application-server/single-server/check-port-useage.md">}} + +## Configure Installation Script + +{{< section "/install-application-server/single-server/add-innovation-only/configure-installation-script.md">}} + +## Test Installation Script + +{{< section "/install-application-server/single-server/test-installation-script.md">}} + +## Run Installation Script + +{{< section "/install-application-server/single-server/run-installation-script.md">}} + +## Add Read and Execute access to Windows Crypto folder + +{{< section "/install-application-server/single-server/add-permissions-to-crypto-folder.md">}} + +## Check Application Services + +{{< section "/install-application-server/single-server/check-application-services.md">}} + +## Preserve installation files + +{{< section "/preserve-installation-files.md">}} + +## Next Steps? + +1. [Install Web Application Server][] + +[Antivirus Exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.AntivirusExclusions" >}} +[Install Web Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallWebApplicationServer" >}} +[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Prerequisites" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-web-application-server.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-web-application-server.md new file mode 100644 index 000000000..bb4ed6d5b --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/install-web-application-server.md @@ -0,0 +1,234 @@ +--- +title: "Install the Web Application Server" +linkTitle: "Install Web Application Server" +description: "Information about installing the Web Application Server." +weight: 40 +--- + +# {{% param title %}} + +This guide describes how to install the Web Application Server components on the server. Please ensure that [Install Application Server][] has been completed before starting this installation. + +## Make Installation Artefacts Available + +1. Copy the following artefacts to a folder on the machine: + + * Cortex Innovation {{< version >}} - Gateway.zip + * Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip + +1. Extract the `Cortex Innovation {{< version >}} - Web App Server Install Scripts.zip` zip file to a folder with the same name. + +## Install Prerequisites + +### Licensing + +Ensure that a valid {{% ctx %}} licence file named `Cortex.lic` exists on the server, in the location `%ProgramData%\Cortex\Licences`. If it does not, follow the instructions located at [Licensing Requirements][]. + +### Get {{% ctx %}} Gateway Application Pool User + +A domain user account is required for the {{% ctx %}} Gateway application pool and must be created prior to performing the installation below. + +In line with best practices, this account should not be given administrator rights, nor should it be used for any purposes other than those specified for {{% ctx %}} Gateway. + +### Grant folder permissions to the {{% ctx %}} Gateway Application Pool User + +The following folders require `Modify` permission to allow creating the `NuGet` folders and its `NuGet.Config` file within: + +* `C:\Windows\System32\config\systemprofile\AppData\Roaming` +* `C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming` + +For each folder, perform the following steps: + +1. Navigate to the `AppData` folder. +1. Right-click on the `Roaming` folder and click `Properties`. +1. In the dialog, click the `Security` tab. +1. Check the `Application Pool` user that will be used for {{% ctx %}} Gateway is listed in the `Group or user names` and has `Modify` permissions. +1. If the `Application Pool` user that will be used for {{% ctx %}} Gateway is not listed: + 1. Click the `Edit...` button. + 1. Click the `Add...` button. + 1. Enter the username of the application pool user and click `OK`. + 1. In the `Permissions` section at the bottom, check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. +1. If the `Application Pool` user that will be used for {{% ctx %}} Gateway is listed but does not have permissions: + 1. Click the `Edit...` button. + 1. Select the `Application Pool` user. + 1. Check `Modify`. + 1. Click `OK`. + 1. Click `Yes` to change the permission to the folder. + +### Certificate Requirements + +{{% ctx %}} Gateway requires an X.509 SSL certificate to be installed on the server. The certificate must have the following properties: + +* Enhanced Key Usage: `Server Authentication` and `Client Authentication` +* Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1 + +If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error. + +{{% alert title="Important" color="warning" %}} +Standard certificates, wildcard certificates, auto-generated self-signed certificates and {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" title="manually created self-signed certificates" >}} can be used. However, self-signed certificates are not recommended for production instances. +
+It is possible to reuse the certificate used when {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScript" title="installing the Application Server" >}}; If doing so, you should {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.AssignCertificateFriendlyName" title="Assign a Certificate Friendly Name" >}} and set the `ImportCertificate` parameter to `$false` in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" title="Configure CORTEX Gateway Installation Script" >}} to ensure use of the correct certificate and to prevent it from being overwritten. +{{% /alert %}} + +#### Import Root Certificate + +{{% alert title="Note" %}}This step is only required if using a self-signed certificate signed by your own Root Certificate e.g. OpenSSL. If this is not the case proceed to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ImportCertificateManually" title="Import Certificate Manually" >}} {{% /alert %}} + +This step must be carried out prior to the installation otherwise the URL validation will fail. In order to import the Root Certificate, ensure that the file is in a known location on this server and complete the following steps: + +1. Using Windows File Explorer navigate to the location of the Root Certificate file. +1. Double click on the Root Certificate file to import the certificate into the Windows Certificate Store. Perform the following steps: + + 1. Select `Local Machine` then click `Next`. + 1. Click `Next`. + 1. Enter the Export Password which the certificate was generated with then click `Next`. + 1. Select `Place all certificates in the following store`. + 1. Click `Browse…`. + 1. Select `Trusted Root Certification Authorities`, click `OK` then click `Next`. + 1. Click `Finish`. + 1. [Import][Import Certificate Manually] the X.509 SSL certificate. + +#### Import Certificate Manually + +{{% alert title="Note" %}}The certificate can be imported automatically by setting the `ImportCertificate` parameter to `$true` in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" title="Configure CORTEX Gateway Installation Script" >}}. If importing the certificate automatically proceed to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.PerformInstallation" title="Perform Installation" >}}

If the certificate has previously been imported you must {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.AssignCertificateFriendlyName" title="assign a friendly name" >}}.{{% /alert %}} + +To import the certificate manually follow the below steps: + +1. Locate the certificate file on the machine and right-click on the file. +1. Select `Install Certificate`. +1. Follow the Wizard and when prompted, ensure you import it into the `Local Machine` store and not `Current User`. +1. Assign the imported certificate a [friendly name][Assign Certificate Friendly Name]. + +#### Assign Certificate Friendly Name + +Once the certificate has been imported, a `Friendly Name` should be assigned which will be used in the [Configure {{% ctx %}} Gateway Installation Script][Configure CORTEX Gateway Installation Script] to enable the installation script to identify the certificate to be used for the website: + +1. Click the Windows button (`Start`). +1. Type `certlm.msc` and press `Enter` to open the Certificate Manager dialog. +1. Expand `Personal` and select `Certificates`. +1. You should see your certificate in this store. +1. Right-click on the certificate and select `Properties`. +1. On the `General` tab in the `Friendly Name` text box, enter a name to be used for the certificate. +1. Click `OK`. + +## Perform Installation + +### Configure {{% ctx %}} Gateway Installation Script + +1. In the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder, locate the `Cortex.Innovation.Install.Gateway.ps1` script and open it with a text editor. +1. Configure the script according to the details given below: + + ```powershell + .\Cortex.Install.Gateway.ps1 ` + -GatewayPackagePath "C:\Install\Cortex Innovation {{< version >}} - Gateway.zip" ` + -FeatureFlags "InnovationId" ` + -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" ` + -ServiceFabricUsingSelfSignedCertificates $false ` + -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" ` + -ServiceFabricApiGatewayBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerEndpoint 'https://server.domain.com:8722/api/' ` + -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" ` + -DotNetFlowDebuggerBasicAuthPassword '#_065077199197085!212123173135087074174142102155007175102029143220132038175026114248243207204119030125106032237087162060168108135168241247037070081~187087056217118!069132229129134129097089241180163#' ` + -DotNetFlowDebuggerUsingSelfSignedCertificates $false ` + -GatewayApplicationPoolUsername "Domain\Username" ` + -WebRootFolder "C:\inetpub\wwwroot" ` + -WebsitePort "443" ` + -ImportCertificate $false ` + -CertificateFilePath "C:\Install\Certificate.pfx" ` + -CertificateFriendlyName "CertificateName" ` + -ConfigureSiteRedirect $true ` + -ApplySecurityMeasures $true ` + -UsingWindowsDefender $false ` + -AcceptEULA:$AcceptEula ` + *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt" + ``` + + {{% alert title="Important" color="warning" %}}Parameters required to be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}} must be encrypted on one of the servers specified in the {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" title="Encryption Requirements" >}} steps.{{% /alert %}} + + | Name | Description | + |------------------------------------------------|-------------| + |`GatewayPackagePath` | Configure this value with the location of the `Cortex Innovation {{< version >}} - Gateway.zip` file on the installation server. | + |`FeatureFlags` | Replace `InnovationId` with the {{% ctx %}} Innovation feature identifier, which should have been provided by {{% ctx %}} when fulfilling the [Licensing Requirements][], if it wasn't it should be requested using [{{% ctx %}} Service Portal][CORTEX Service Portal].

This will set the `FeatureFlags` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricApiGatewayEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the server. The port should be specified as `8722` and there must be a trailing slash, e.g. `https://server.domain.com:8722/`.

This will set the `ServiceFabricApiGatewayEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricUsingSelfSignedCertificates` | Configure the value as `$false` if you used valid CA certificates when [installing the Application Server][Configure Installation Script], `$true` if you used self-signed certificates.

This will set the `ServiceFabricUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`ServiceFabricApiGatewayBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`ServiceFabricApiGatewayBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Application Server][Configure Installation Script]; if so, this value must be configured to the one used.

This will set the `ServiceFabricApiGatewayBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerEndpoint` | Replace `server.domain.com` with the fully qualified domain name of the Web Application Server.

This will set the `DotNetFlowDebuggerEndpoint` value in the {{% ctx %}} Gateway web.config.| + |`DotNetFlowDebuggerBasicAuthUsername` | This must be changed if you used a non-default `ApiGatewayBasicAuthUsername` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthUsername` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter should be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerBasicAuthPassword` | This must be changed if you used a non-default `ApiGatewayBasicAuthPassword` when [installing the Debugger on the Web Application Server][Install Application Server]; if so, this value must be configured to the one used.

This will set the `DotNetFlowDebuggerBasicAuthPassword` value in the {{% ctx %}} Gateway web.config.{{< alert type="note" title="Note" >}} This parameter must be {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" title="CORTEX Encrypted" >}}.{{< /alert >}}| + |`DotNetFlowDebuggerUsingSelfSignedCertificates` | Configure the value as `$false` if you are using valid CA certificates to secure the communication between {{% ctx %}} Gateway and the Debugger, `$true` if using self-signed certificates.

This will set the `DotNetFlowDebuggerUsingSelfSignedCertificates` value in the {{% ctx %}} Gateway web.config.| + |`GatewayApplicationPoolUsername` | Replace `Domain\Username` with the user that should be used to run the {{% ctx %}} Gateway application pool as configured in [Get {{% ctx %}} Gateway Application Pool User][Get CORTEX Gateway Application Pool User].| + |`WebRootFolder` | Replace this with the correct path for the Web Root Folder on the server. Typically this will be `C:\inetpub\wwwroot`.| + |`WebsitePort` | Replace this with the port that you wish the website to use. Typically this will be `443`.| + |`ImportCertificate` | Change this from `$true` to `$false` if you do not require the certificate to be imported as part of the installation process.

Note that if this is changed to `$false` you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation.| + |`CertificateFilePath` | Replace this with the location and filename for the certificate to be imported.

If `ImportCertificate` is set to `$false` this value can remain unchanged but you must [import the Root Certificate][Import Root Certificate] (if necessary), [import the X.509 certificate manually][Import Certificate Manually] and [assign a friendly name][Assign Certificate Friendly Name] prior to running the installation.| + |`CertificateFriendlyName` | Replace this with the friendly name that you would like to be allocated to the certificate.

If `ImportCertificate` is set to `$false` this must be [assigned][Assign Certificate Friendly Name] prior to running the installation and the Friendly Name used must be specified to allow the website to use the correct certificate.| + |`ConfigureSiteRedirect` | If the site hosting the {{% ctx %}} Gateway web application is a newly created {{% ctx %}} site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the {{% ctx %}} Gateway web application URL. The default behaviour of the script is to create a URL Rewrite redirect rule to achieve this.

To skip this rule creation change the value to `$false`.| + |`ApplySecurityMeasures` | Change this from `$true` to `$false` if you do not require the Recommended [Security Best Practices][] to be implemented as part of the installation process.| + |`UsingWindowsDefender` | Change this from `$false` to `$true` if you are using the Windows Defender firewall.

If Windows Defender is not being used but an alternative firewall is, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443).| + |`AcceptEULA` | This does not need to be changed, the EULA will be accepted at a later stage. | + |`FilePath` | The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified. | + +1. Save and close `Cortex.Innovation.Install.Gateway.ps1`. + +### Install {{% ctx %}} Gateway + +1. Open a Windows PowerShell (x64) window as administrator. +1. Navigate PowerShell to inside the `Cortex Innovation {{< version >}} - Web App Server Install Scripts` folder using the following command, modifying the path as necessary: + + ```powershell + cd "C:\Install\Cortex Innovation {{< version >}} - Web App Server Install Scripts" + ``` + +1. Type the following command into PowerShell: + + ```powershell + .\Cortex.Innovation.Install.Gateway.ps1 + ``` + +1. Please read the End User Licence Agreement which can be found [here][Eula]. Once you agree to the terms, add the flag `-AcceptEULA` to the command entered above, e.g: + + ```powershell + .\.ps1 -AcceptEULA + ``` + +1. Run the PowerShell command to install {{% ctx %}} Gateway. +1. If `ImportCertificate` is set to $true, and the file is of type `.pfx`, a prompt will appear for the certificate password. This should be entered, and then hit `Enter`. +1. A prompt will appear to enter the password for the user specified to run the {{% ctx %}} Gateway Application Pool. This should be entered, and then hit `Enter`. +1. Check that there have been no errors in the script; these would appear in red in the console. + + If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation. + + If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance. + +1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine. You can choose to restart now (`N`) or later (`L`). +1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `://:/`, e.g. `https://localhost/gateway` and wait for the login page to load. + +### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User + +{{< section "/install-web-application-server/add-innovation-only/grant-gateway-user-additional-folder-permissions.md">}} + +## Preserve installation files + +Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates. + +## Next Steps? + +1. [Setup Gateway][] + +[Assign Certificate Friendly Name]: {{< ref "#assign-certificate-friendly-name" >}} +[Configure CORTEX Gateway Installation Script]: {{< ref "#configure-cortex-gateway-installation-script" >}} +[Configure Installation Script]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScript" >}} +[CORTEX Encrypted]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.EncryptText" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Encryption Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.EncryptionRequirements" >}} +[Eula]: {{< url path="Cortex.Website.Eula.MainDoc" >}} +[Get CORTEX Gateway Application Pool User]: {{< ref "#get-cortex-gateway-application-pool-user" >}} +[Import Certificate Manually]: {{< ref "#import-certificate-manually" >}} +[Import Root Certificate]: {{< ref path="#import-root-certificate" >}} +[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallApplicationServer" >}} +[Licensing Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.LicensingRequirements" >}} +[Security Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.SetupGateway" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/prerequisites.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/prerequisites.md new file mode 100644 index 000000000..8a53074c8 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/prerequisites.md @@ -0,0 +1,232 @@ +--- +title: "Prerequisites" +linkTitle: "Prerequisites" +description: "Information about the prerequisites required on each server type for installation." +weight: 20 +--- + +# {{% param title %}} + +The prerequisites required for a single server (as described in [Architecture][]) are laid out in this guide. These must be considered before undertaking installation. + +## Hardware Requirements + +{{% alert title="Note" %}}This configuration is not recommended for production servers that are required to scale and support HA.{{% /alert %}} + +| Server Role | Servers Required | CPU Cores (> 2GHz) | RAM (GB) | Disk (GB) | +|------------------|-----------------------|-----------------------------------|---------------|----------------------| +| Single Server
*Application Server +
Web Application Server* | 1 | 4+ *Recommended*
2 *Minimum* | 16+ *Recommended*
12 *Minimum* | 150+ *Recommended*
100 *Minimum*
30+ free on installation drive
40+ free on %ProgramData% drive | + +## Software Requirements + +| Server Role | Windows Server[^1] | .Net | PowerShell[^2] | IIS[^3] | Other Software | +|------------------|-------------------------|---------------------|------|------------|---------| +| Single Server
*Application Server +
Web Application Server* | [2022 (x64)][Microsoft Server 2022] *Recommended*
[2019 (x64)][Microsoft Server 2019] | [Framework 4.7.2][NET Framework 472] | 5.1 | 10.0.20348[^4]
10.0.17763[^5]
[URL Rewrite Module 2.1][IIS Url Rewrite] | [Microsoft Web Deploy 3.0 or later][Web Deploy]
[Visual C++ Redistributable 2013 (x64)][C++ Redistributable] | + +[^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future. +[^2]: PowerShell 5.1 ships with Windows Server 2019 and 2022. +[^3]: IIS is supported; other web servers, including IIS Express are not supported. +[^4]: Ships as a windows role within Windows Server 2022. +[^5]: Ships as a windows role within Windows Server 2019. + +## Domain Requirements + +The server must be on a domain and cannot be a domain controller. + +## Active Directory Requirements + +For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported. + +Supported versions of Active Directory are listed below: + +| Version | Verified? | Supported From | Supported Until | +|----------------------------|----------------|----------------|------------------| +| Windows Server 2003 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2003 R2 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2008 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2012 R2 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2016 | ✓ | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2019 | | {{% ctx %}} v2022.9 | To be evaluated | +| Windows Server 2022 | | {{% ctx %}} v2022.9 | To be evaluated | + +## DNS Requirements + +The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server. + +## Licensing Requirements + +A valid {{% ctx %}} licence file and {{% ctx %}} Innovation feature identifier must be procured from {{% ctx %}}. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the server and it should contain that server's fingerprint. + +To get a licence file and feature identifier take the following steps: + +1. Copy the following template to a text file: + + ```text + Web Application/Application Server + MachineID: + Fingerprint: + + Please also include a suitable {{% ctx %}} Innovation feature identifier. + ``` + +1. Extract `Cortex Innovation {{< version >}} - Licence Fingerprint Generator.zip`. +1. From that folder, copy `Cortex.Licensing.FingerprintGeneration.exe` to the server. +1. Double-click `Cortex.Licensing.FingerprintGeneration.exe` to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g: + + ```text + MachineID: SERVER + Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6 + ``` + +1. Copy the output (machine identifier and fingerprint) to the `Web Application/Application Server` section of the text file created in the initial step. Note that the machine identifier can be changed to any string. +1. Request a licence and feature identifier by raising a case in the [{{% ctx %}} Service Portal][CORTEX Service Portal], including the contents of the text file containing all of the fingerprint and machine information in the body of the case. +1. When the licence and feature identifier have arrived, copy the file `Cortex.lic` to `%ProgramData%\Cortex\Licences` on the Web Application Server, creating the `Cortex` and `Licences` folders if they don't exist. Save the feature identifier for use when [Installing Gateway][]. + +## Web Browser Requirements + +Gateway supports the latest versions of the following browsers: + +* Chrome +* Edge +* Firefox + +## Filesystem Requirements + +The server must use an NTFS filesystem. + +## Service Requirements + +The following Windows Services must be running on the server: + +* Performance Logs & Alerts +* Remote Registry +* Windows Event Log + +## Security Requirements + +### Installation User + +A domain user which is a member of the Local Administrators group on the server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the platform that {{% ctx %}} Innovation is built upon. + +### IIS Application Pool User + +For Gateway, a domain user must be available to run the IIS Application Pool. This user must be given `Log on as a service` and `Log on as a batch job` permissions otherwise the Application Pool will not be able to run. Information about how to do this will be given during installation. + +### Antivirus Exclusions + +It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the server to reduce antivirus processing on Service Fabric artefacts: + +Folder Exclusions: + +* %ProgramFiles%\Microsoft Service Fabric +* %ProgramData%\SF +* %ProgramData%\SF\Logs + +Process Exclusions: + +* Fabric.exe +* FabricHost.exe +* FabricInstallerService.exe +* FabricSetup.exe +* FabricDeployer.exe +* ImageBuilder.exe +* FabricGateway.exe +* FabricDCA.exe +* FabricFAS.exe +* FabricUOS.exe +* FabricRM.exe +* FileStoreService.exe + +A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually. + +If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist. + +### Port Requirements + +{{% ctx %}} Innovation and Microsoft Service Fabric require a range of [firewall ports to be opened][Port Requirements] between the server and specific services. + +If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in [Port Requirements][] to open the correct ports. + +The `Cortex.Innovation.Test.PortUsage.ps1` script is provided during installation to test the ports on the server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible. + +### Certificate Requirements + +{{< alert title="Important" color="warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}} + +#### Application Servers + +{{% alert title="Note" %}} +For production systems it is recommended that an X.509 SSL certificate is obtained from a Certificate Authority and used for installation. For non-production systems, certificates can be omitted from installation and it will create and use self-signed certificates. This may prevent 3rd parties that require valid certificate verification to access the API Gateway Service. +{{% / alert %}} + +An X.509 SSL certificate (standard or wildcard) should be used to: + +* Allow Application Services to identify themselves to clients such as Gateway. +* Prevent unauthorised nodes from joining the single node cluster. +* Connect to Service Fabric Explorer from the Application Server. +* Connect to Gateway. + +The certificate can be obtained from a Certificate Authority, such as [Let’s Encrypt](), and must meet the following requirements: + +* Subject field must be in one of the following formats, depending on the certificate type: + * Standard certificates must use the standard format (e.g. `CN=host.domain.com`). + * Wildcard certificates must use the wildcard format, pertaining to the domain of the server (e.g. `CN=*.domain.com`). +* Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service. +* Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1. It must include any additional host names that should be able to be used to access the API Gateway Service. +* Certificate file must be in a .PFX file format, with a known password. +* Certificate file must contain the full chain of certificates. +* Certificate file must include the private key. +* Key Usage extension must have a value of `Digital Signature, Key Encipherment (a0)`. +* Enhanced Key Usage must include `Server Authentication` and `Client Authentication`. + +This file should be placed in a known location on the server. This location will be required when running the Application Server installation script. + +#### Web Application Server + +{{% ctx %}} Gateway requires an X.509 SSL certificate to be installed on the Web Application Server. The certificate must have the following properties: + +* Enhanced Key Usage: `Server Authentication` and `Client Authentication` +* Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1 + +If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error. + +{{% alert title="Important" color="warning" %}} +Standard certificates, wildcard certificates, auto-generated self-signed certificates and {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" title="manually created self-signed certificates" >}} can be used. However, self-signed certificates are not recommended for production instances. +
+It is possible to reuse the certificate used when {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScript" title="installing the Application Server" >}}; If doing so, you should set the `ImportCertificate` parameter to `$false` in {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" title="Configure CORTEX Gateway Installation Script" >}} step to prevent overwriting. +{{% /alert %}} + +More information about importing the certificate is given during installation. + +### TLS Requirements + +There is a set of non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following: + +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + +See [SSL Best Practices][] for a full list of the security changes which will be applied. The `Cortex.Innovation.Install.SSLBestPractices.ps1` script is provided during installation to apply these security changes to the server. + +### Encryption Requirements + +{{< section "/prerequisites/install-innovation-only/single-server/encryption-requirements.md">}} + +## Next Steps? + +1. [Install Application Server][] + +[Architecture]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Architecture" >}} +[C++ Redistributable]: {{< url path="MSDownload.CPlusPlusRedistributable.2013" >}} +[CORTEX Service Portal]: {{< url path="Cortex.ServicePortal.MainDoc" >}} +[Create Self-Signed Certificates]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.CreateSelfSignedCertificates" >}} +[IIS URL Rewrite]: {{< url path="IIS.Downloads.UrlRewrite-2_1" >}} +[Install Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallApplicationServer" >}} +[Installing Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureCortexGatewayInstallationScript" >}} +[Microsoft Server 2019]: {{< url path="MSEval.WindowsServer.2019" >}} +[Microsoft Server 2022]: {{< url path="MSEval.WindowsServer.2022" >}} +[NET Framework 472]: {{< url path="MSDotNet.Framework472.MainDoc" >}} +[Port Requirements]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.PortRequirements" >}} +[SSL Best Practices]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.SSLBestPractices" >}} +[Web Deploy]: {{< url path="MSDownload.WebDeploy" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/setup-gateway.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/setup-gateway.md new file mode 100644 index 000000000..05ea8ea2f --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/setup-gateway.md @@ -0,0 +1,84 @@ +--- +title: "Setup Gateway" +linkTitle: "Setup Gateway" +description: "Information about setting up {{% ctx %}} Gateway for first-time use." +weight: 50 +--- + +# {{% param title %}} + +This guide describes how to setup Gateway. Please ensure that [Install Web Application Server][] has been completed before taking these steps. + +## Gateway Initial Setup + +Log on to Gateway and run through the setup wizard: + +1. Open a [supported web browser][] and navigate to `://:/`, e.g. `https://server.domain.com/gateway`. + + If an error message is displayed in the browser, wait a few minutes and refresh the page as it is possible that the website was still starting. +1. Log on using the default credentials that Gateway deploys with: + + Username: `administrator` + + Password: `Adm1n1strat0r` +1. On a newly installed system, you will be presented with a Setup Wizard at this point, which will guide you through some basic configuration steps: + * [Account Details] + * [LDAP Connection] + * [LDAP Authorisation] +1. Follow the steps in the setup wizard to configure the relevant areas: + + ### Account Details + + 1. Click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup1.png" title="Initial Setup Screen" >}} + 1. Enter an email address for the Administrator and click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup2.png" title="Administrator Details Screen" >}} + 1. Change the Administrator password to a unique, secret password and click `Next Step`: + {{< figure class="centre" src="/images/Gateway Setup3.png" title="Change Password Screen" >}} + + ### LDAP Connection + + 1. Enter the details of your Active Directory server and provide a Username and Password for a user with read access to it: + + A connection to an Active Directory server must be established in order to assign authorisation rights to users. + 1. In the `Server` field, enter the Hostname, FQDN or IP Address of the Active Directory server that Gateway should use to authenticate and authorise users. + 1. In the `Port` field, enter the port number of the Active Directory server. The well-known port for LDAP traffic is `389`; if SSL encryption is used, the well-known port is `636`. + 1. If an SSL connection is to be used, tick the box `Use SSL`. + 1. In the `Username` field, enter a valid username of a user that has read permissions for the Active Directory server. + 1. In the `Password` field, enter the password of the user entered in the previous step. + 1. To reduce the scope of any Active Directory searches, add one or more base DNs (Distinguished Names). For each base DN click `Add` and enter the full LDAP path e.g `CN=group, OU=organisational unit, DC=domain, DC=com`. These will be used as the roots of any Active Directory searches performed. For more information about distinguished names see . + 1. Click `Test Connection` to validate the connection and the user credentials entered and click `Next Step`. + + {{< figure class="centre" src="/images/Gateway Setup4.png" title="LDAP Connection Screen" >}} + + ### LDAP Authorisation + + 1. If the authorisation grid fails to load first time round, click `Retry`. + 1. Assign access permissions to Active Directory groups: + + To allow users to access the various roles within Gateway, it is first necessary to assign them the appropriate access rights. + Gateway currently supports four roles, but only two are relevant for {{% ctx %}} Innovation: + + * Admin + * Studio + + To give a user access to a role, set access for a group or Organisational Unit (OU) that the user is a member of: + + 1. Expand the groups or OUs, or search for the group or OU, to be assigned one or more roles. + 1. Check the relevant roles for each group. Checking a parent group will cascade the setting to all child groups. + + {{< figure class="centre" src="/images/Gateway Setup5.png" title="LDAP Authorisation Screen" >}} + + 1. Click `Complete Setup` to commit the changes. + 1. To test the permissions, log out as Administrator and then log in as a user with `Studio` permissions. + +## Next Steps? + +1. [Try it out][] + +[Account Details]: {{< ref "#account-details" >}} +[LDAP Authorisation]: {{< ref "#ldap-authorisation" >}} +[LDAP Connection]: {{< ref "#ldap-connection" >}} +[Install Web Application Server]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.InstallWebApplicationServer" >}} +[supported web browser]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.WebBrowserRequirements" >}} +[Try it out]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.TryItOut" >}} diff --git a/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/try-it-out.md b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/try-it-out.md new file mode 100644 index 000000000..90fe675a9 --- /dev/null +++ b/content/en/docs/2024.9/getting-started/on-premise/install-innovation-only/single-server-without-ha/try-it-out.md @@ -0,0 +1,66 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out {{% ctx %}} Innovation for the first time." +weight: 60 +--- + +# {{% param title %}} + +This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that [Setup Gateway][] has been completed before taking these steps. + +## Test Debugging Flows + +Test the platform by creating a new flow and executing it using the following steps: + +1. Click on the `Dev` charm, then the `+` button and click `Group` to open a dialog. +1. Enter a name for the group, configure the `Permission Groups` and click `OK` to create the group. +1. Click on the group to open it (refresh the page if it does not appear). +1. Inside the group, click the `+` button again and click on `Activity` 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. 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, 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 Flow` and `End Flow` 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 Variables Grid, set `Is Output Variable?` to `true` for the new `Result` variable. +1. Add a breakpoint to the `End Flow` block and start the flow. An execution token should appear. + If the token does not appear, try refreshing the page. Failing that, see [Troubleshooting][Troubleshooting Flow Not Starting]. +1. Select the execution in the Executions Grid (bottom panel). +1. The `Result` variable displayed in the Variables Viewer (right panel) should show the current time. +1. Continue or stop the execution. +1. Commit the flow. + +## Test Publishing Production Flows + +1. Log in to Gateway with a user that has the `Admin` role. +1. Click on the `Admin` charm, then `Packages`. +1. Click `Add Package Definition`. Enter a package name and select the new flow to add to the package. Click `Save` to save the new package. +1. Click `Publish`. A success message should appear. If it doesn't it means that either one or more of the parameters prefixed with `Service Fabric` in the `CortexGateway.SetParameters.xml` file was not set properly when installing Gateway, or the Application Services aren't healthy. See [Troubleshooting][Troubleshooting No Publish] for more information. + +## Test Executing Production Flows + +1. Open an HTTP client, such as [Postman](https://www.postman.com/downloads/). Make a request with the following format: + | Property | Value | + |---------------|-------------------------------------------------------------------------------------| + | Action | POST | + | URL | https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
e.g. https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage| + | Content Type | application/json | + | Body | {} | + | Authentication| Basic | + | Username | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services | + | Password | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted) | + + {{% alert title="Note" %}} If you used self-signed certificates when installing the server you will need to disable SSL certificate validation in your HTTP client. {{% /alert %}} + +1. The request should return a JSON object with the output variables of the flow e.g. `{ "Output": "2022-03-09T07:35:16+0000" }`. +1. {{% ctx %}} Innovation has now been verified and is ready to use. + +[Setup Gateway]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.SetupGateway" >}} +[Troubleshooting During Installation]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingDuringInstallation" >}} +[Troubleshooting Flow No Blocks]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNoBlocks" >}} +[Troubleshooting Flow Not Starting]: {{< url path="Cortex.Reference.Troubleshooting.Installation.TroubleshootingFlowNotStarting" >}} +[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/static/2024.7/pdf/Cortex Interaction Portal Developer Guide.pdf b/content/static/2024.7/pdf/Cortex Interaction Portal Developer Guide.pdf index a3453af92..cb271dc4d 100644 Binary files a/content/static/2024.7/pdf/Cortex Interaction Portal Developer Guide.pdf and b/content/static/2024.7/pdf/Cortex Interaction Portal Developer Guide.pdf differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_CreateCollection_CreateCollectionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_CreateCollection_CreateCollectionBlock.png new file mode 100644 index 000000000..3784e559b Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_CreateCollection_CreateCollectionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteCollection_DeleteCollectionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteCollection_DeleteCollectionBlock.png new file mode 100644 index 000000000..f86d3dbd2 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteCollection_DeleteCollectionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteData_DeleteDataWithKeyBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteData_DeleteDataWithKeyBlock.png new file mode 100644 index 000000000..f86d3dbd2 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_DeleteData_DeleteDataWithKeyBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_ReadData_ReadDataWithKeyBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_ReadData_ReadDataWithKeyBlock.png new file mode 100644 index 000000000..1a488011d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_ReadData_ReadDataWithKeyBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToExistBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToExistBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToExistBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToNotExistBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToNotExistBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForCollection_WaitForCollectionToNotExistBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToBeSetBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToBeSetBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToBeSetBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToContainValueBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToContainValueBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToContainValueBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToExistBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToExistBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToExistBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToNotExistBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToNotExistBlock.png new file mode 100644 index 000000000..da597fddb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WaitForKeyInCollection_WaitForKeyInCollectionToNotExistBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WriteData_WriteDataWithKeyBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WriteData_WriteDataWithKeyBlock.png new file mode 100644 index 000000000..34f602b0e Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DataStorage_WriteData_WriteDataWithKeyBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Data_ExecuteDataCommand_ExecuteDataCommandBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Data_ExecuteDataCommand_ExecuteDataCommandBlock_1.png new file mode 100644 index 000000000..e934a7750 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Data_ExecuteDataCommand_ExecuteDataCommandBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_AddTimePeriod_AddTimePeriodBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_AddTimePeriod_AddTimePeriodBlock.png new file mode 100644 index 000000000..7e9ab5e5f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_AddTimePeriod_AddTimePeriodBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertDateTimeToTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertDateTimeToTextBlock.png new file mode 100644 index 000000000..e11adfdef Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertDateTimeToTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertTextToDateTimeBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertTextToDateTimeBlock.png new file mode 100644 index 000000000..e11adfdef Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_ConvertDateTime_ConvertTextToDateTimeBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetCurrentDateTimeBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetCurrentDateTimeBlock.png new file mode 100644 index 000000000..1538ff0f2 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetCurrentDateTimeBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetDateTimeComponentBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetDateTimeComponentBlock.png new file mode 100644 index 000000000..1538ff0f2 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetDateTime_GetDateTimeComponentBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetTimePeriod_GetTimePeriodBetweenDateTimesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetTimePeriod_GetTimePeriodBetweenDateTimesBlock.png new file mode 100644 index 000000000..1538ff0f2 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_GetTimePeriod_GetTimePeriodBetweenDateTimesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeAfterBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeAfterBlock.png new file mode 100644 index 000000000..cda2adcaa Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeAfterBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBeforeBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBeforeBlock.png new file mode 100644 index 000000000..cda2adcaa Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBeforeBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBetweenBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBetweenBlock.png new file mode 100644 index 000000000..cda2adcaa Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeBetweenBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeEqualBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeEqualBlock.png new file mode 100644 index 000000000..cda2adcaa Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_IsDateTime_IsDateTimeEqualBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_SubtractTimePeriod_SubtractTimePeriodBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_SubtractTimePeriod_SubtractTimePeriodBlock.png new file mode 100644 index 000000000..874e52626 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_DateAndTime_SubtractTimePeriod_SubtractTimePeriodBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitBottomBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitBottomBlock_1.png new file mode 100644 index 000000000..18a6d908f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitBottomBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitRightBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitRightBlock_1.png new file mode 100644 index 000000000..18a6d908f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfNullExitRightBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitBottomBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitBottomBlock.png new file mode 100644 index 000000000..18a6d908f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitBottomBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitRightBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitRightBlock.png new file mode 100644 index 000000000..18a6d908f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Decisions_If_IfTrueExitRightBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_AddItem_AddItemWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_AddItem_AddItemWithKeyBlock_3.png new file mode 100644 index 000000000..dd9fc60e5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_AddItem_AddItemWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyAndValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyAndValueBlock_3.png new file mode 100644 index 000000000..b4897f2a9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyAndValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyBlock_3.png new file mode 100644 index 000000000..b4897f2a9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithValueBlock_3.png new file mode 100644 index 000000000..b4897f2a9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithKeysBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithKeysBlock_3.png new file mode 100644 index 000000000..b4897f2a9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithKeysBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithValuesBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithValuesBlock_3.png new file mode 100644 index 000000000..b4897f2a9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_ContainsItem_ContainsItemsWithValuesBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfAllItemsBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfAllItemsBlock_3.png new file mode 100644 index 000000000..2c4a66e86 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfAllItemsBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfItemsWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfItemsWithValueBlock_3.png new file mode 100644 index 000000000..2c4a66e86 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountOfItemsWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountsOfItemsWithValuesBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountsOfItemsWithValuesBlock_3.png new file mode 100644 index 000000000..2c4a66e86 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetCount_GetCountsOfItemsWithValuesBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetAllItemsBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetAllItemsBlock_3.png new file mode 100644 index 000000000..cee407e09 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetAllItemsBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemWithKeyBlock_3.png new file mode 100644 index 000000000..cee407e09 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemsWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemsWithKeyBlock_3.png new file mode 100644 index 000000000..cee407e09 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetItem_GetItemsWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetKey_GetAllKeysBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetKey_GetAllKeysBlock_3.png new file mode 100644 index 000000000..cee407e09 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_GetKey_GetAllKeysBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveAllItemsBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveAllItemsBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveAllItemsBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithKeyBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithValueBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeyBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeysBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeysBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithKeysBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValueBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValuesBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValuesBlock_3.png new file mode 100644 index 000000000..8981935c8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_RemoveItem_RemoveItemsWithValuesBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetAllItemsBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetAllItemsBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetAllItemsBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithKeyBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithValueBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeyBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeyBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeyBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeysBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeysBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithKeysBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValueBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValueBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValueBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValuesBlock_3.png b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValuesBlock_3.png new file mode 100644 index 000000000..f1f2ace3f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Dictionaries_SetItem_SetItemsWithValuesBlock_3.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Email_SendEmail_SendEmailUsingSmtpServerBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Email_SendEmail_SendEmailUsingSmtpServerBlock.png new file mode 100644 index 000000000..8ec802540 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Email_SendEmail_SendEmailUsingSmtpServerBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionBlock.png new file mode 100644 index 000000000..010d4d4cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessageBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessageBlock.png new file mode 100644 index 000000000..010d4d4cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessageBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessagesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessagesBlock.png new file mode 100644 index 000000000..010d4d4cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingMessagesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNameBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNameBlock.png new file mode 100644 index 000000000..010d4d4cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNameBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNamesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNamesBlock.png new file mode 100644 index 000000000..010d4d4cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleBlockException_HandleBlockExceptionMatchingTypeNamesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleFlowException_HandleFlowExceptionWorkspaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleFlowException_HandleFlowExceptionWorkspaceBlock.png new file mode 100644 index 000000000..495a0a175 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleFlowException_HandleFlowExceptionWorkspaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleWorkspaceException_HandleWorkspaceExceptionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleWorkspaceException_HandleWorkspaceExceptionBlock.png new file mode 100644 index 000000000..4db384bbb Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_HandleWorkspaceException_HandleWorkspaceExceptionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_RethrowException_RethrowExceptionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_RethrowException_RethrowExceptionBlock.png new file mode 100644 index 000000000..86c20e6ac Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_RethrowException_RethrowExceptionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_ThrowException_ThrowNewFlowExceptionBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_ThrowException_ThrowNewFlowExceptionBlock.png new file mode 100644 index 000000000..4344f3b03 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Exceptions_ThrowException_ThrowNewFlowExceptionBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFile_CheckFileExistsBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFile_CheckFileExistsBlock.png new file mode 100644 index 000000000..55db42419 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFile_CheckFileExistsBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFolder_CheckFolderExistsBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFolder_CheckFolderExistsBlock.png new file mode 100644 index 000000000..790e7ecb1 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CheckFolder_CheckFolderExistsBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFileBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFileBlock.png new file mode 100644 index 000000000..df414d2f5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFileBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFilesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFilesBlock.png new file mode 100644 index 000000000..df414d2f5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFile_CopyFilesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFolderBlock.png new file mode 100644 index 000000000..ad53eea8a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFoldersBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFoldersBlock.png new file mode 100644 index 000000000..ad53eea8a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_CopyFoldersBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_DuplicateFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_DuplicateFolderBlock.png new file mode 100644 index 000000000..ad53eea8a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CopyFolder_DuplicateFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFolderBlock.png new file mode 100644 index 000000000..c018b7497 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFoldersBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFoldersBlock.png new file mode 100644 index 000000000..c018b7497 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_CreateFolder_CreateFoldersBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFileBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFileBlock.png new file mode 100644 index 000000000..d1b40036b Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFileBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFilesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFilesBlock.png new file mode 100644 index 000000000..d1b40036b Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFile_DeleteFilesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFolderBlock.png new file mode 100644 index 000000000..a3a65e353 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFoldersBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFoldersBlock.png new file mode 100644 index 000000000..a3a65e353 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_DeleteFolder_DeleteFoldersBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFileInformation_GetFileInformationBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFileInformation_GetFileInformationBlock.png new file mode 100644 index 000000000..937d26bb5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFileInformation_GetFileInformationBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderContent_GetFolderContentBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderContent_GetFolderContentBlock.png new file mode 100644 index 000000000..1de3b69a6 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderContent_GetFolderContentBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderInformation_GetFolderInformationBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderInformation_GetFolderInformationBlock.png new file mode 100644 index 000000000..c5f0dd3a5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_GetFolderInformation_GetFolderInformationBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFileBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFileBlock.png new file mode 100644 index 000000000..e1bbd6f66 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFileBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFilesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFilesBlock.png new file mode 100644 index 000000000..e1bbd6f66 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFile_MoveFilesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFolderBlock.png new file mode 100644 index 000000000..f6fd538ab Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFoldersBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFoldersBlock.png new file mode 100644 index 000000000..f6fd538ab Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_MoveFolder_MoveFoldersBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllLinesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllLinesBlock.png new file mode 100644 index 000000000..9ebf2f36c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllLinesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllTextBlock.png new file mode 100644 index 000000000..9ebf2f36c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_ReadFile_ReadAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_RenameFolder_RenameFolderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_RenameFolder_RenameFolderBlock.png new file mode 100644 index 000000000..3d117fd99 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_RenameFolder_RenameFolderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFileBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFileBlock.png new file mode 100644 index 000000000..f12b4f6ba Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFileBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFilesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFilesBlock.png new file mode 100644 index 000000000..f12b4f6ba Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_SearchFile_SearchFilesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllLinesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllLinesBlock.png new file mode 100644 index 000000000..ffb97ef7b Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllLinesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllTextBlock.png new file mode 100644 index 000000000..ffb97ef7b Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_FilesAndFolders_WriteFile_WriteAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Flows_EndFlow_EndFlowBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Flows_EndFlow_EndFlowBlock.png new file mode 100644 index 000000000..be0baea4d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Flows_EndFlow_EndFlowBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowAsyncBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowAsyncBlock.png new file mode 100644 index 000000000..f2741cc23 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowAsyncBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowBlock.png new file mode 100644 index 000000000..f2741cc23 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Flows_RunFlow_RunFlowBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Flows_StartFlow_StartFlowBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Flows_StartFlow_StartFlowBlock.png new file mode 100644 index 000000000..1d4e95200 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Flows_StartFlow_StartFlowBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_GoogleWorkspace_Gmail_SendEmail_SendEmailUsingGmailBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_GoogleWorkspace_Gmail_SendEmail_SendEmailUsingGmailBlock.png new file mode 100644 index 000000000..943009e0a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_GoogleWorkspace_Gmail_SendEmail_SendEmailUsingGmailBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteHttpRequest_ExecuteHttpRequestBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteHttpRequest_ExecuteHttpRequestBlock_1.png new file mode 100644 index 000000000..a2cae2fc9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteHttpRequest_ExecuteHttpRequestBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteSoapRequest_ExecuteSoapRequestBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteSoapRequest_ExecuteSoapRequestBlock_1.png new file mode 100644 index 000000000..5a88f76e8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Http_ExecuteSoapRequest_ExecuteSoapRequestBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertJsonToObjectBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertJsonToObjectBlock.png new file mode 100644 index 000000000..5be022c93 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertJsonToObjectBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertObjectToJsonBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertObjectToJsonBlock.png new file mode 100644 index 000000000..5be022c93 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Json_ConvertJson_ConvertObjectToJsonBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtBeginningBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtEndBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtIndexBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtBeginningBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtEndBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtIndexBlock_2.png new file mode 100644 index 000000000..8b875e031 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_AddItem_AddItemsAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemWithValueBlock_2.png new file mode 100644 index 000000000..3becaf2a5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemsWithValuesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemsWithValuesBlock_2.png new file mode 100644 index 000000000..3becaf2a5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_ContainsItem_ContainsItemsWithValuesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfAllItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfAllItemsBlock_2.png new file mode 100644 index 000000000..ac5891fdc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfAllItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfItemsWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfItemsWithValueBlock_2.png new file mode 100644 index 000000000..ac5891fdc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountOfItemsWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountsOfItemsWithValuesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountsOfItemsWithValuesBlock_2.png new file mode 100644 index 000000000..ac5891fdc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetCount_GetCountsOfItemsWithValuesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexOfItemWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexOfItemWithValueBlock_2.png new file mode 100644 index 000000000..db7646130 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexOfItemWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexesOfItemsWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexesOfItemsWithValueBlock_2.png new file mode 100644 index 000000000..db7646130 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetIndex_GetIndexesOfItemsWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtBeginningBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtEndBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtIndexBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtBeginningBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtEndBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexesBlock_2.png new file mode 100644 index 000000000..e7ffa940c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_GetItem_GetItemsAtIndexesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveAllItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveAllItemsBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveAllItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveDuplicateItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveDuplicateItemsBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveDuplicateItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtBeginningBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtEndBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtIndexBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemWithValueBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtBeginningBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtEndBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexesBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsAtIndexesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValueBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValuesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValuesBlock_2.png new file mode 100644 index 000000000..b30cbb72f Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_RemoveItem_RemoveItemsWithValuesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetAllItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetAllItemsBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetAllItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtBeginningBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtEndBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtIndexBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemWithValueBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtBeginningBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtBeginningBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtBeginningBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtEndBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtEndBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtEndBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexesBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsAtIndexesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValueBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValueBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValueBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValuesBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValuesBlock_2.png new file mode 100644 index 000000000..7c00986f9 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Lists_SetItem_SetItemsWithValuesBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Logs_LogEvent_LogEventBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Logs_LogEvent_LogEventBlock.png new file mode 100644 index 000000000..d5ec4fbe1 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Logs_LogEvent_LogEventBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Loops_ForEach_ForEachLoopBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Loops_ForEach_ForEachLoopBlock.png new file mode 100644 index 000000000..cee2c2ad3 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Loops_ForEach_ForEachLoopBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Loops_For_ForLoopBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Loops_For_ForLoopBlock.png new file mode 100644 index 000000000..a13816ca1 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Loops_For_ForLoopBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Microsoft365_Outlook_SendEmail_SendEmailUsingMicrosoft365Block.png b/content/static/2024.9/blocks/Cortex_Blocks_Microsoft365_Outlook_SendEmail_SendEmailUsingMicrosoft365Block.png new file mode 100644 index 000000000..9a80a4a59 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Microsoft365_Outlook_SendEmail_SendEmailUsingMicrosoft365Block.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Objects_ConvertObject_ConvertObjectToTextBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Objects_ConvertObject_ConvertObjectToTextBlock_1.png new file mode 100644 index 000000000..372e1686e Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Objects_ConvertObject_ConvertObjectToTextBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Objects_CopyObject_CopyObjectBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Objects_CopyObject_CopyObjectBlock_1.png new file mode 100644 index 000000000..a24c9d8d1 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Objects_CopyObject_CopyObjectBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_PowerShell_ExecutePowerShellScript_ExecutePowerShellScriptBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_PowerShell_ExecutePowerShellScript_ExecutePowerShellScriptBlock_1.png new file mode 100644 index 000000000..cf657baa8 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_PowerShell_ExecutePowerShellScript_ExecutePowerShellScriptBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemBlock_2.png new file mode 100644 index 000000000..eb96aab56 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemsBlock_2.png new file mode 100644 index 000000000..eb96aab56 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_DequeueItem_DequeueItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemBlock_2.png new file mode 100644 index 000000000..c00424502 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemsBlock_2.png new file mode 100644 index 000000000..c00424502 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_EnqueueItem_EnqueueItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_GetCount_GetCountOfAllItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_GetCount_GetCountOfAllItemsBlock_2.png new file mode 100644 index 000000000..ee0948060 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_GetCount_GetCountOfAllItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_PeekItem_PeekItemBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_PeekItem_PeekItemBlock_2.png new file mode 100644 index 000000000..bbf212335 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_PeekItem_PeekItemBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Queues_RemoveItem_RemoveAllItemsBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Queues_RemoveItem_RemoveAllItemsBlock_2.png new file mode 100644 index 000000000..1f714a803 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Queues_RemoveItem_RemoveAllItemsBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Schedules_WaitFor_WaitForDurationBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Schedules_WaitFor_WaitForDurationBlock.png new file mode 100644 index 000000000..ed46841a3 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Schedules_WaitFor_WaitForDurationBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Ssh_ExecuteSshCommand_ExecuteSshCommandBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Ssh_ExecuteSshCommand_ExecuteSshCommandBlock.png new file mode 100644 index 000000000..e17e1eb12 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Ssh_ExecuteSshCommand_ExecuteSshCommandBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelAllTasksBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelAllTasksBlock_2.png new file mode 100644 index 000000000..4f01a5716 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelAllTasksBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelTaskBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelTaskBlock_1.png new file mode 100644 index 000000000..4f01a5716 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_CancelTask_CancelTaskBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForAllTasksBlock_2.png b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForAllTasksBlock_2.png new file mode 100644 index 000000000..335e53d77 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForAllTasksBlock_2.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForTaskBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForTaskBlock_1.png new file mode 100644 index 000000000..335e53d77 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Tasks_WaitForTask_WaitForTaskBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Telnet_ExecuteTelnetCommand_ExecuteTelnetCommandBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Telnet_ExecuteTelnetCommand_ExecuteTelnetCommandBlock.png new file mode 100644 index 000000000..6eebf5663 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Telnet_ExecuteTelnetCommand_ExecuteTelnetCommandBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAfterIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAfterIndexBlock.png new file mode 100644 index 000000000..66babfadc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAfterIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtBeginningBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtBeginningBlock.png new file mode 100644 index 000000000..66babfadc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtBeginningBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtEndBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtEndBlock.png new file mode 100644 index 000000000..66babfadc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextAtEndBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextBeforeIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextBeforeIndexBlock.png new file mode 100644 index 000000000..66babfadc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_AddText_AddTextBeforeIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAllTextBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAnyTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAnyTextBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsAnyTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsTextBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ContainsText_ContainsTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToCamelCaseBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToCamelCaseBlock.png new file mode 100644 index 000000000..0068e7ca5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToCamelCaseBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToLowerCaseBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToLowerCaseBlock.png new file mode 100644 index 000000000..0068e7ca5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToLowerCaseBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToPascalCaseBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToPascalCaseBlock.png new file mode 100644 index 000000000..0068e7ca5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToPascalCaseBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToTitleCaseBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToTitleCaseBlock.png new file mode 100644 index 000000000..0068e7ca5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToTitleCaseBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToUpperCaseBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToUpperCaseBlock.png new file mode 100644 index 000000000..0068e7ca5 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_ConvertTo_ConvertToUpperCaseBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_DecodeText_DecodeTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_DecodeText_DecodeTextBlock.png new file mode 100644 index 000000000..022ed7c0a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_DecodeText_DecodeTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_EncodeText_EncodeTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_EncodeText_EncodeTextBlock.png new file mode 100644 index 000000000..a4fce8c6e Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_EncodeText_EncodeTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveAllTextBlock.png new file mode 100644 index 000000000..7d29a60cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveTextBlock.png new file mode 100644 index 000000000..7d29a60cc Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndRemoveText_FindAndRemoveTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceAllTextBlock.png new file mode 100644 index 000000000..86794035a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceTextBlock.png new file mode 100644 index 000000000..86794035a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindAndReplaceText_FindAndReplaceTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindAllTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindAllTextBlock.png new file mode 100644 index 000000000..720b5ab73 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindAllTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindTextBlock.png new file mode 100644 index 000000000..720b5ab73 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FindText_FindTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValueBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValueBlock_1.png new file mode 100644 index 000000000..5f79d9538 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValueBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValuesBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValuesBlock_1.png new file mode 100644 index 000000000..5f79d9538 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_FormatText_FormatTextWithValuesBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexOfTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexOfTextBlock.png new file mode 100644 index 000000000..64a06988c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexOfTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexesOfTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexesOfTextBlock.png new file mode 100644 index 000000000..64a06988c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetIndex_GetIndexesOfTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetLength_GetLengthBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetLength_GetLengthBlock.png new file mode 100644 index 000000000..a1946bf08 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetLength_GetLengthBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtBeginningBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtBeginningBlock.png new file mode 100644 index 000000000..2f30cef60 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtBeginningBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtEndBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtEndBlock.png new file mode 100644 index 000000000..2f30cef60 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtEndBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtIndexBlock.png new file mode 100644 index 000000000..64a06988c Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextAtIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBeforeIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBeforeIndexBlock.png new file mode 100644 index 000000000..2f30cef60 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBeforeIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBetweenIndexesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBetweenIndexesBlock.png new file mode 100644 index 000000000..2f30cef60 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_GetText_GetTextBetweenIndexesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyOrWhitespaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyOrWhitespaceBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEmptyOrWhitespaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEqualBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEqualBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextEqualBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullEmptyOrWhitespaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullEmptyOrWhitespaceBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullEmptyOrWhitespaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullOrEmptyBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullOrEmptyBlock.png new file mode 100644 index 000000000..97f0bfd72 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_IsText_IsTextNullOrEmptyBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_JoinText_JoinTextBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_JoinText_JoinTextBlock_1.png new file mode 100644 index 000000000..d2f5c0e39 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_JoinText_JoinTextBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtBeginningBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtBeginningBlock.png new file mode 100644 index 000000000..c7adb776d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtBeginningBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtEndBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtEndBlock.png new file mode 100644 index 000000000..c7adb776d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtEndBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtIndexBlock.png new file mode 100644 index 000000000..c7adb776d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextAtIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBeforeIndexBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBeforeIndexBlock.png new file mode 100644 index 000000000..c7adb776d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBeforeIndexBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBetweenIndexesBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBetweenIndexesBlock.png new file mode 100644 index 000000000..c7adb776d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_RemoveText_RemoveTextBetweenIndexesBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Text_SplitText_SplitTextBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Text_SplitText_SplitTextBlock.png new file mode 100644 index 000000000..eff74f740 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Text_SplitText_SplitTextBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Variables_SetVariable_SetVariableBlock_1.png b/content/static/2024.9/blocks/Cortex_Blocks_Variables_SetVariable_SetVariableBlock_1.png new file mode 100644 index 000000000..085b875b4 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Variables_SetVariable_SetVariableBlock_1.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessReceiver_WirelessReceiverBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessReceiver_WirelessReceiverBlock.png new file mode 100644 index 000000000..74381372d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessReceiver_WirelessReceiverBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessSender_WirelessSenderBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessSender_WirelessSenderBlock.png new file mode 100644 index 000000000..669321639 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Wireless_WirelessSender_WirelessSenderBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_EndWorkspace_EndWorkspaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_EndWorkspace_EndWorkspaceBlock.png new file mode 100644 index 000000000..37d96105e Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_EndWorkspace_EndWorkspaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_StartWorkspace_StartWorkspaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_StartWorkspace_StartWorkspaceBlock.png new file mode 100644 index 000000000..d07c5493d Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_StartWorkspace_StartWorkspaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_Workspace_WorkspaceBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_Workspace_WorkspaceBlock.png new file mode 100644 index 000000000..9fbc0230a Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Workspaces_Workspace_WorkspaceBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertStructureToXmlBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertStructureToXmlBlock.png new file mode 100644 index 000000000..74bfd5086 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertStructureToXmlBlock.png differ diff --git a/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertXmlToStructureBlock.png b/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertXmlToStructureBlock.png new file mode 100644 index 000000000..74bfd5086 Binary files /dev/null and b/content/static/2024.9/blocks/Cortex_Blocks_Xml_ConvertXml_ConvertXmlToStructureBlock.png differ diff --git a/content/static/2024.9/images/Gateway Setup1.png b/content/static/2024.9/images/Gateway Setup1.png new file mode 100644 index 000000000..6fa7a984e Binary files /dev/null and b/content/static/2024.9/images/Gateway Setup1.png differ diff --git a/content/static/2024.9/images/Gateway Setup2.png b/content/static/2024.9/images/Gateway Setup2.png new file mode 100644 index 000000000..1077d2d37 Binary files /dev/null and b/content/static/2024.9/images/Gateway Setup2.png differ diff --git a/content/static/2024.9/images/Gateway Setup3.png b/content/static/2024.9/images/Gateway Setup3.png new file mode 100644 index 000000000..0fd42a1ca Binary files /dev/null and b/content/static/2024.9/images/Gateway Setup3.png differ diff --git a/content/static/2024.9/images/Gateway Setup4.png b/content/static/2024.9/images/Gateway Setup4.png new file mode 100644 index 000000000..30d21549c Binary files /dev/null and b/content/static/2024.9/images/Gateway Setup4.png differ diff --git a/content/static/2024.9/images/Gateway Setup5.png b/content/static/2024.9/images/Gateway Setup5.png new file mode 100644 index 000000000..9915ffc7d Binary files /dev/null and b/content/static/2024.9/images/Gateway Setup5.png differ diff --git a/content/static/2024.9/images/Grafana Cloud - Create Stack.png b/content/static/2024.9/images/Grafana Cloud - Create Stack.png new file mode 100644 index 000000000..857e585b6 Binary files /dev/null and b/content/static/2024.9/images/Grafana Cloud - Create Stack.png differ diff --git a/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Data.png b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Data.png new file mode 100644 index 000000000..e78811787 Binary files /dev/null and b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Data.png differ diff --git a/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Token Name.png b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Token Name.png new file mode 100644 index 000000000..9d8c8f71a Binary files /dev/null and b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Token Name.png differ diff --git a/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Usecase.png b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Usecase.png new file mode 100644 index 000000000..9f5fe061f Binary files /dev/null and b/content/static/2024.9/images/Grafana Cloud - Hosted Logs Config Usecase.png differ diff --git a/content/static/2024.9/images/GrafanaMenuIcon.png b/content/static/2024.9/images/GrafanaMenuIcon.png new file mode 100644 index 000000000..f60edfc99 Binary files /dev/null and b/content/static/2024.9/images/GrafanaMenuIcon.png differ diff --git a/content/static/2024.9/images/IIS Bindings.png b/content/static/2024.9/images/IIS Bindings.png new file mode 100644 index 000000000..72a3390e9 Binary files /dev/null and b/content/static/2024.9/images/IIS Bindings.png differ diff --git a/content/static/2024.9/images/Network Discovery 1.png b/content/static/2024.9/images/Network Discovery 1.png new file mode 100644 index 000000000..77d41e935 Binary files /dev/null and b/content/static/2024.9/images/Network Discovery 1.png differ diff --git a/content/static/2024.9/images/Network Discovery 2.png b/content/static/2024.9/images/Network Discovery 2.png new file mode 100644 index 000000000..a3352f631 Binary files /dev/null and b/content/static/2024.9/images/Network Discovery 2.png differ diff --git a/content/static/2024.9/images/Network Discovery 3.png b/content/static/2024.9/images/Network Discovery 3.png new file mode 100644 index 000000000..21f73ee4f Binary files /dev/null and b/content/static/2024.9/images/Network Discovery 3.png differ diff --git a/content/static/2024.9/images/New Innovation Flow View.PNG b/content/static/2024.9/images/New Innovation Flow View.PNG new file mode 100644 index 000000000..4f5c9a202 Binary files /dev/null and b/content/static/2024.9/images/New Innovation Flow View.PNG differ diff --git a/content/static/2024.9/images/RabbitMQ Status.png b/content/static/2024.9/images/RabbitMQ Status.png new file mode 100644 index 000000000..a061d3882 Binary files /dev/null and b/content/static/2024.9/images/RabbitMQ Status.png differ diff --git a/content/static/2024.9/images/Screenshots.pptx b/content/static/2024.9/images/Screenshots.pptx new file mode 100644 index 000000000..7f3f1ecb8 Binary files /dev/null and b/content/static/2024.9/images/Screenshots.pptx differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Expiring Certificate.PNG b/content/static/2024.9/images/Service Fabric Explorer - Expiring Certificate.PNG new file mode 100644 index 000000000..8ed424b4d Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Expiring Certificate.PNG differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Instance - Single.png b/content/static/2024.9/images/Service Fabric Explorer - Instance - Single.png new file mode 100644 index 000000000..4e24c6289 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Instance - Single.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Instance.png b/content/static/2024.9/images/Service Fabric Explorer - Instance.png new file mode 100644 index 000000000..8d4d44ec1 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Instance.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Node - Single.png b/content/static/2024.9/images/Service Fabric Explorer - Node - Single.png new file mode 100644 index 000000000..3fbd3a752 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Node - Single.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Node.png b/content/static/2024.9/images/Service Fabric Explorer - Node.png new file mode 100644 index 000000000..224e8285f Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Node.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Service - Single.png b/content/static/2024.9/images/Service Fabric Explorer - Service - Single.png new file mode 100644 index 000000000..9f79b92f6 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Service - Single.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Service.png b/content/static/2024.9/images/Service Fabric Explorer - Service.png new file mode 100644 index 000000000..5a2f10e0c Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Service.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer - Single.png b/content/static/2024.9/images/Service Fabric Explorer - Single.png new file mode 100644 index 000000000..d29e19f42 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer - Single.png differ diff --git a/content/static/2024.9/images/Service Fabric Explorer.png b/content/static/2024.9/images/Service Fabric Explorer.png new file mode 100644 index 000000000..0ac2f69b2 Binary files /dev/null and b/content/static/2024.9/images/Service Fabric Explorer.png differ diff --git a/content/static/2024.9/images/Url Rewrite Icon.png b/content/static/2024.9/images/Url Rewrite Icon.png new file mode 100644 index 000000000..eb39ad05b Binary files /dev/null and b/content/static/2024.9/images/Url Rewrite Icon.png differ diff --git a/content/static/2024.9/images/Variable-Scopes.png b/content/static/2024.9/images/Variable-Scopes.png new file mode 100644 index 000000000..d570b9ecc Binary files /dev/null and b/content/static/2024.9/images/Variable-Scopes.png differ diff --git a/content/static/2024.9/images/WaitForAllTasksExample.png b/content/static/2024.9/images/WaitForAllTasksExample.png new file mode 100644 index 000000000..902ec903e Binary files /dev/null and b/content/static/2024.9/images/WaitForAllTasksExample.png differ diff --git a/content/static/2024.9/images/Web Platform Installer Icon.png b/content/static/2024.9/images/Web Platform Installer Icon.png new file mode 100644 index 000000000..3c46e2541 Binary files /dev/null and b/content/static/2024.9/images/Web Platform Installer Icon.png differ diff --git a/content/static/2024.9/images/_ReadMe.md b/content/static/2024.9/images/_ReadMe.md new file mode 100644 index 000000000..d6b14a07e --- /dev/null +++ b/content/static/2024.9/images/_ReadMe.md @@ -0,0 +1,9 @@ +# Editing the files + +All images in the `editable` folder are editable and can be modified using [Diagrams Online](https://app.diagrams.net/) or [Diagrams Desktop](https://github.com/jgraph/drawio-desktop/releases/) + +## Service Fabric Cluster Screenshots + +Refresh rate has been turned off. +All screenshots have been taken at 1500px width and 700px height using Device Emulation. +The div displaying the time at the bottom-right corner has also been removed. diff --git a/content/static/2024.9/images/action-blocks.svg b/content/static/2024.9/images/action-blocks.svg new file mode 100644 index 000000000..aba26ad0a --- /dev/null +++ b/content/static/2024.9/images/action-blocks.svg @@ -0,0 +1,4 @@ + + + +
Input Port
Input Port
Output Port
Output Port
Exception Output Port
Exception O...Text is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/block-exception.gif b/content/static/2024.9/images/block-exception.gif new file mode 100644 index 000000000..ce7ee1462 Binary files /dev/null and b/content/static/2024.9/images/block-exception.gif differ diff --git a/content/static/2024.9/images/chained-exception.gif b/content/static/2024.9/images/chained-exception.gif new file mode 100644 index 000000000..3b605fc67 Binary files /dev/null and b/content/static/2024.9/images/chained-exception.gif differ diff --git a/content/static/2024.9/images/chaining-handle-block-exception-blocks.png b/content/static/2024.9/images/chaining-handle-block-exception-blocks.png new file mode 100644 index 000000000..bae9f14e1 Binary files /dev/null and b/content/static/2024.9/images/chaining-handle-block-exception-blocks.png differ diff --git a/content/static/2024.9/images/child-execution-in-grid.PNG b/content/static/2024.9/images/child-execution-in-grid.PNG new file mode 100644 index 000000000..3f865fc81 Binary files /dev/null and b/content/static/2024.9/images/child-execution-in-grid.PNG differ diff --git a/content/static/2024.9/images/decision-blocks.svg b/content/static/2024.9/images/decision-blocks.svg new file mode 100644 index 000000000..d721b1c05 --- /dev/null +++ b/content/static/2024.9/images/decision-blocks.svg @@ -0,0 +1,4 @@ + + + +
Input Port
Input Port
Bottom
Output Port
Bottom...
Right Output Port
Right Output PortText is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/discarded-variable.PNG b/content/static/2024.9/images/discarded-variable.PNG new file mode 100644 index 000000000..00b770bb9 Binary files /dev/null and b/content/static/2024.9/images/discarded-variable.PNG differ diff --git a/content/static/2024.9/images/editable/Cortex Innovation Node Details.png b/content/static/2024.9/images/editable/Cortex Innovation Node Details.png new file mode 100644 index 000000000..654b14425 Binary files /dev/null and b/content/static/2024.9/images/editable/Cortex Innovation Node Details.png differ diff --git a/content/static/2024.9/images/editable/Cortex Innovation Overview-Single Server.png b/content/static/2024.9/images/editable/Cortex Innovation Overview-Single Server.png new file mode 100644 index 000000000..00fa17102 Binary files /dev/null and b/content/static/2024.9/images/editable/Cortex Innovation Overview-Single Server.png differ diff --git a/content/static/2024.9/images/editable/Cortex Innovation Overview.png b/content/static/2024.9/images/editable/Cortex Innovation Overview.png new file mode 100644 index 000000000..237b68000 Binary files /dev/null and b/content/static/2024.9/images/editable/Cortex Innovation Overview.png differ diff --git a/content/static/2024.9/images/editable/Cortex Innovation and v7.2 Best Architecture.png b/content/static/2024.9/images/editable/Cortex Innovation and v7.2 Best Architecture.png new file mode 100644 index 000000000..4824d67cf Binary files /dev/null and b/content/static/2024.9/images/editable/Cortex Innovation and v7.2 Best Architecture.png differ diff --git a/content/static/2024.9/images/editable/Cortex Innovation v7.2 Single Server.png b/content/static/2024.9/images/editable/Cortex Innovation v7.2 Single Server.png new file mode 100644 index 000000000..e72f2bb26 Binary files /dev/null and b/content/static/2024.9/images/editable/Cortex Innovation v7.2 Single Server.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Duration.png b/content/static/2024.9/images/editable/Flow Execution Requests - Duration.png new file mode 100644 index 000000000..6d667c4d6 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Duration.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Errors.png b/content/static/2024.9/images/editable/Flow Execution Requests - Errors.png new file mode 100644 index 000000000..e5d91a5d6 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Errors.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Filters.png b/content/static/2024.9/images/editable/Flow Execution Requests - Filters.png new file mode 100644 index 000000000..93844dcc6 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Filters.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Not Zero.png b/content/static/2024.9/images/editable/Flow Execution Requests - Not Zero.png new file mode 100644 index 000000000..a142188a9 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Not Zero.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Overview.png b/content/static/2024.9/images/editable/Flow Execution Requests - Overview.png new file mode 100644 index 000000000..c520d02f2 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Overview.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Requests.png b/content/static/2024.9/images/editable/Flow Execution Requests - Requests.png new file mode 100644 index 000000000..b10a40956 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Requests.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Time Range extended.png b/content/static/2024.9/images/editable/Flow Execution Requests - Time Range extended.png new file mode 100644 index 000000000..7ad059abb Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Time Range extended.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests - Time Range.png b/content/static/2024.9/images/editable/Flow Execution Requests - Time Range.png new file mode 100644 index 000000000..954ba9ed9 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests - Time Range.png differ diff --git a/content/static/2024.9/images/editable/Flow Execution Requests Dashboard.png b/content/static/2024.9/images/editable/Flow Execution Requests Dashboard.png new file mode 100644 index 000000000..a264cfb99 Binary files /dev/null and b/content/static/2024.9/images/editable/Flow Execution Requests Dashboard.png differ diff --git a/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - Cloud.png b/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - Cloud.png new file mode 100644 index 000000000..249d19958 Binary files /dev/null and b/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - Cloud.png differ diff --git a/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - On-Premise.png b/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - On-Premise.png new file mode 100644 index 000000000..3f7a8e417 Binary files /dev/null and b/content/static/2024.9/images/editable/Grafana Platform Architecture Diagram - On-Premise.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Availability.png b/content/static/2024.9/images/editable/Platform Health - Availability.png new file mode 100644 index 000000000..5adef29b0 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Availability.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Break in Line.png b/content/static/2024.9/images/editable/Platform Health - Break in Line.png new file mode 100644 index 000000000..004c29249 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Break in Line.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Duration.png b/content/static/2024.9/images/editable/Platform Health - Duration.png new file mode 100644 index 000000000..00667ca13 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Duration.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Errors.png b/content/static/2024.9/images/editable/Platform Health - Errors.png new file mode 100644 index 000000000..677b2b864 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Errors.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Filters.png b/content/static/2024.9/images/editable/Platform Health - Filters.png new file mode 100644 index 000000000..cf3f2dddf Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Filters.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Not Zeros.png b/content/static/2024.9/images/editable/Platform Health - Not Zeros.png new file mode 100644 index 000000000..9346fad19 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Not Zeros.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Overview.png b/content/static/2024.9/images/editable/Platform Health - Overview.png new file mode 100644 index 000000000..74b6e9d6d Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Overview.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Requests.png b/content/static/2024.9/images/editable/Platform Health - Requests.png new file mode 100644 index 000000000..db4e36407 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Requests.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Time Range extended.png b/content/static/2024.9/images/editable/Platform Health - Time Range extended.png new file mode 100644 index 000000000..4ec8ad256 Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Time Range extended.png differ diff --git a/content/static/2024.9/images/editable/Platform Health - Time Range.png b/content/static/2024.9/images/editable/Platform Health - Time Range.png new file mode 100644 index 000000000..a3f623ffc Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health - Time Range.png differ diff --git a/content/static/2024.9/images/editable/Platform Health Dashboard.png b/content/static/2024.9/images/editable/Platform Health Dashboard.png new file mode 100644 index 000000000..22f43ea2b Binary files /dev/null and b/content/static/2024.9/images/editable/Platform Health Dashboard.png differ diff --git a/content/static/2024.9/images/editable/editor-types.png b/content/static/2024.9/images/editable/editor-types.png new file mode 100644 index 000000000..444627859 Binary files /dev/null and b/content/static/2024.9/images/editable/editor-types.png differ diff --git a/content/static/2024.9/images/editable/exception-handling-blocks.png b/content/static/2024.9/images/editable/exception-handling-blocks.png new file mode 100644 index 000000000..05c399218 Binary files /dev/null and b/content/static/2024.9/images/editable/exception-handling-blocks.png differ diff --git a/content/static/2024.9/images/editable/expression-editor.png b/content/static/2024.9/images/editable/expression-editor.png new file mode 100644 index 000000000..5660a4321 Binary files /dev/null and b/content/static/2024.9/images/editable/expression-editor.png differ diff --git a/content/static/2024.9/images/editable/variable-editor.png b/content/static/2024.9/images/editable/variable-editor.png new file mode 100644 index 000000000..8e4504cd4 Binary files /dev/null and b/content/static/2024.9/images/editable/variable-editor.png differ diff --git a/content/static/2024.9/images/exception-in-viewer.PNG b/content/static/2024.9/images/exception-in-viewer.PNG new file mode 100644 index 000000000..139faf1a8 Binary files /dev/null and b/content/static/2024.9/images/exception-in-viewer.PNG differ diff --git a/content/static/2024.9/images/execution-in-grid.PNG b/content/static/2024.9/images/execution-in-grid.PNG new file mode 100644 index 000000000..6239053b2 Binary files /dev/null and b/content/static/2024.9/images/execution-in-grid.PNG differ diff --git a/content/static/2024.9/images/flow-control-blocks.svg b/content/static/2024.9/images/flow-control-blocks.svg new file mode 100644 index 000000000..f2bc68403 --- /dev/null +++ b/content/static/2024.9/images/flow-control-blocks.svg @@ -0,0 +1,4 @@ + + + +
Input Port
Input Port
Output Port
Output PortText is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/flow-error-status.png b/content/static/2024.9/images/flow-error-status.png new file mode 100644 index 000000000..75eaf5533 Binary files /dev/null and b/content/static/2024.9/images/flow-error-status.png differ diff --git a/content/static/2024.9/images/flow-exception-full-configuration.png b/content/static/2024.9/images/flow-exception-full-configuration.png new file mode 100644 index 000000000..3d8b57780 Binary files /dev/null and b/content/static/2024.9/images/flow-exception-full-configuration.png differ diff --git a/content/static/2024.9/images/flow-exception-no-configuration.png b/content/static/2024.9/images/flow-exception-no-configuration.png new file mode 100644 index 000000000..26eb9baaf Binary files /dev/null and b/content/static/2024.9/images/flow-exception-no-configuration.png differ diff --git a/content/static/2024.9/images/flow-exception.gif b/content/static/2024.9/images/flow-exception.gif new file mode 100644 index 000000000..e731245b3 Binary files /dev/null and b/content/static/2024.9/images/flow-exception.gif differ diff --git a/content/static/2024.9/images/loading.gif b/content/static/2024.9/images/loading.gif new file mode 100644 index 000000000..1b1dd085a Binary files /dev/null and b/content/static/2024.9/images/loading.gif differ diff --git a/content/static/2024.9/images/messages-grid.PNG b/content/static/2024.9/images/messages-grid.PNG new file mode 100644 index 000000000..768f9fbd9 Binary files /dev/null and b/content/static/2024.9/images/messages-grid.PNG differ diff --git a/content/static/2024.9/images/nested-workspace.svg b/content/static/2024.9/images/nested-workspace.svg new file mode 100644 index 000000000..13c1ccf82 --- /dev/null +++ b/content/static/2024.9/images/nested-workspace.svg @@ -0,0 +1,4 @@ + + + +
Start Workspace Block
Start Workspace...
Action Blocks
Action...
End Workspace Block
End Workspace Bl...
Handle Workspace Execution Block
Handle Workspace E...
Action Block
Action Block
End Flow Block
End Flow BlockText is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-command-panel.png b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-command-panel.png new file mode 100644 index 000000000..88809b778 Binary files /dev/null and b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-command-panel.png differ diff --git a/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-dictionary-panel.png b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-dictionary-panel.png new file mode 100644 index 000000000..a3eedad09 Binary files /dev/null and b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-dictionary-panel.png differ diff --git a/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-exception-panel.png b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-exception-panel.png new file mode 100644 index 000000000..3d9fafa4e Binary files /dev/null and b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-exception-panel.png differ diff --git a/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-variable-panel-2.png b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-variable-panel-2.png new file mode 100644 index 000000000..57fabec9b Binary files /dev/null and b/content/static/2024.9/images/reference/concepts/fundamentals/variables/what-is-a-variable-variable-panel-2.png differ diff --git a/content/static/2024.9/images/rethrow-from-list-exception.png b/content/static/2024.9/images/rethrow-from-list-exception.png new file mode 100644 index 000000000..d2ce32fa3 Binary files /dev/null and b/content/static/2024.9/images/rethrow-from-list-exception.png differ diff --git a/content/static/2024.9/images/rethrow-from-subflow.gif b/content/static/2024.9/images/rethrow-from-subflow.gif new file mode 100644 index 000000000..18940097a Binary files /dev/null and b/content/static/2024.9/images/rethrow-from-subflow.gif differ diff --git a/content/static/2024.9/images/rethrow-original-list-exception.png b/content/static/2024.9/images/rethrow-original-list-exception.png new file mode 100644 index 000000000..01c394ed8 Binary files /dev/null and b/content/static/2024.9/images/rethrow-original-list-exception.png differ diff --git a/content/static/2024.9/images/run-flow-contract-change.gif b/content/static/2024.9/images/run-flow-contract-change.gif new file mode 100644 index 000000000..51f7ec586 Binary files /dev/null and b/content/static/2024.9/images/run-flow-contract-change.gif differ diff --git a/content/static/2024.9/images/run-flow-selecting-a-flow.gif b/content/static/2024.9/images/run-flow-selecting-a-flow.gif new file mode 100644 index 000000000..412bafc8c Binary files /dev/null and b/content/static/2024.9/images/run-flow-selecting-a-flow.gif differ diff --git a/content/static/2024.9/images/send-email-using-smtp-server-html-email.png b/content/static/2024.9/images/send-email-using-smtp-server-html-email.png new file mode 100644 index 000000000..c2050372f Binary files /dev/null and b/content/static/2024.9/images/send-email-using-smtp-server-html-email.png differ diff --git a/content/static/2024.9/images/send-email-using-smtp-server-important-email.png b/content/static/2024.9/images/send-email-using-smtp-server-important-email.png new file mode 100644 index 000000000..ee37bff62 Binary files /dev/null and b/content/static/2024.9/images/send-email-using-smtp-server-important-email.png differ diff --git a/content/static/2024.9/images/set-variable/set-variable-block-timeout.svg b/content/static/2024.9/images/set-variable/set-variable-block-timeout.svg new file mode 100644 index 000000000..5f098e155 --- /dev/null +++ b/content/static/2024.9/images/set-variable/set-variable-block-timeout.svg @@ -0,0 +1,4 @@ + + + +
Hide Advanced
Hide Advan...
Show Advanced
Show Advan...
Show
Show
Hide
HideText is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/set-variable/set-variable-description.svg b/content/static/2024.9/images/set-variable/set-variable-description.svg new file mode 100644 index 000000000..4faeedfed --- /dev/null +++ b/content/static/2024.9/images/set-variable/set-variable-description.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-arithmetic.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-arithmetic.PNG new file mode 100644 index 000000000..94c427ff1 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-arithmetic.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-boolean-and.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-boolean-and.PNG new file mode 100644 index 000000000..4c7994890 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-boolean-and.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-boolean.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-boolean.PNG new file mode 100644 index 000000000..fe7251640 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-boolean.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-casting.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-casting.PNG new file mode 100644 index 000000000..e12f18ec6 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-casting.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-char.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-char.PNG new file mode 100644 index 000000000..4687890b4 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-char.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-comparison.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-comparison.PNG new file mode 100644 index 000000000..cc59f28d6 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-comparison.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-concatenated-string.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-concatenated-string.PNG new file mode 100644 index 000000000..f64996f13 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-concatenated-string.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-constructor.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-constructor.PNG new file mode 100644 index 000000000..db9dc1683 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-constructor.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-decomposition.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-decomposition.PNG new file mode 100644 index 000000000..de501792e Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-decomposition.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-double.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-double.PNG new file mode 100644 index 000000000..d5870fd13 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-double.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-empty.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-empty.PNG new file mode 100644 index 000000000..2b987804b Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-empty.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-enum.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-enum.PNG new file mode 100644 index 000000000..0185623ee Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-enum.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-index.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-index.PNG new file mode 100644 index 000000000..1c1164094 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-index.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-int.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-int.PNG new file mode 100644 index 000000000..2fd85c96f Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-int.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-int64.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-int64.PNG new file mode 100644 index 000000000..7da49c8de Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-int64.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-interpolated-string.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-interpolated-string.PNG new file mode 100644 index 000000000..15765291d Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-interpolated-string.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-list.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-list.PNG new file mode 100644 index 000000000..cf0a87248 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-list.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-method.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-method.PNG new file mode 100644 index 000000000..cec4c8326 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-method.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-properties.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-properties.PNG new file mode 100644 index 000000000..93d69e2b3 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-properties.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-single.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-single.PNG new file mode 100644 index 000000000..121237327 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-single.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-string.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-string.PNG new file mode 100644 index 000000000..da7f51396 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-string.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-structure.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-structure.PNG new file mode 100644 index 000000000..837633104 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-structure.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-variable.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-variable.PNG new file mode 100644 index 000000000..00a22a925 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-variable.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-expression-verbatim-string.PNG b/content/static/2024.9/images/set-variable/set-variable-expression-verbatim-string.PNG new file mode 100644 index 000000000..0eefdd4b7 Binary files /dev/null and b/content/static/2024.9/images/set-variable/set-variable-expression-verbatim-string.PNG differ diff --git a/content/static/2024.9/images/set-variable/set-variable-run-as.svg b/content/static/2024.9/images/set-variable/set-variable-run-as.svg new file mode 100644 index 000000000..c00068912 --- /dev/null +++ b/content/static/2024.9/images/set-variable/set-variable-run-as.svg @@ -0,0 +1,4 @@ + + + +
Hide Advanced
Hide Advan...
Show Advanced
Show Advan...
Hide
Hide
Show
ShowText is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/top-level-workspace-activity.svg b/content/static/2024.9/images/top-level-workspace-activity.svg new file mode 100644 index 000000000..993b1b26b --- /dev/null +++ b/content/static/2024.9/images/top-level-workspace-activity.svg @@ -0,0 +1,4 @@ + + + +
Start Flow Block
Start Flow...
Action Block
Action...
Decision Block
Decision...
Workspace Blocks
Workspace...
End Flow Block
End Flow B...
Handle Flow Exception Block
Handle Flow Exc...Text is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/top-level-workspace-process.svg b/content/static/2024.9/images/top-level-workspace-process.svg new file mode 100644 index 000000000..2c662ece9 --- /dev/null +++ b/content/static/2024.9/images/top-level-workspace-process.svg @@ -0,0 +1,4 @@ + + + +
Action Block
Action...
Handle Flow Exception Block
Handle Flow Exc...
Workspace Blocks
Workspace...
Start Flow Block
Start Flow Block
Action Block
Action...
End Flow Block
End Flow...Text is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/variables-grid.PNG b/content/static/2024.9/images/variables-grid.PNG new file mode 100644 index 000000000..ed75cb620 Binary files /dev/null and b/content/static/2024.9/images/variables-grid.PNG differ diff --git a/content/static/2024.9/images/work-in-progress.jpg b/content/static/2024.9/images/work-in-progress.jpg new file mode 100644 index 000000000..7ea01e421 Binary files /dev/null and b/content/static/2024.9/images/work-in-progress.jpg differ diff --git a/content/static/2024.9/images/workspace-blocks.svg b/content/static/2024.9/images/workspace-blocks.svg new file mode 100644 index 000000000..d86c8074f --- /dev/null +++ b/content/static/2024.9/images/workspace-blocks.svg @@ -0,0 +1,4 @@ + + + +
Input Port
Input Port
Output Port
Output Port
Exception
Output Port
Exception...Text is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/images/workspace-exception.gif b/content/static/2024.9/images/workspace-exception.gif new file mode 100644 index 000000000..4efcf2696 Binary files /dev/null and b/content/static/2024.9/images/workspace-exception.gif differ diff --git a/content/static/2024.9/images/workspace/workspace-block-semaphore.svg b/content/static/2024.9/images/workspace/workspace-block-semaphore.svg new file mode 100644 index 000000000..4308b927e --- /dev/null +++ b/content/static/2024.9/images/workspace/workspace-block-semaphore.svg @@ -0,0 +1,4 @@ + + + +
Show
Show
Hide
Hide
Show
Advanced
Show...
Hide
Advanced
Hide...Text is not SVG - cannot display \ No newline at end of file diff --git a/content/static/2024.9/pdf/Cortex Interaction Portal Deployment Guide.pdf b/content/static/2024.9/pdf/Cortex Interaction Portal Deployment Guide.pdf new file mode 100644 index 000000000..ed469d5fc Binary files /dev/null and b/content/static/2024.9/pdf/Cortex Interaction Portal Deployment Guide.pdf differ diff --git a/content/static/2024.9/pdf/Cortex Interaction Portal Developer Guide.pdf b/content/static/2024.9/pdf/Cortex Interaction Portal Developer Guide.pdf new file mode 100644 index 000000000..7599f169d Binary files /dev/null and b/content/static/2024.9/pdf/Cortex Interaction Portal Developer Guide.pdf differ diff --git a/content/static/2024.9/pdf/Cortex Interaction Portal Merging Guide.pdf b/content/static/2024.9/pdf/Cortex Interaction Portal Merging Guide.pdf new file mode 100644 index 000000000..9aa14919f Binary files /dev/null and b/content/static/2024.9/pdf/Cortex Interaction Portal Merging Guide.pdf differ diff --git a/content/static/2024.9/pdf/Cortex Interaction Portal User Guide.pdf b/content/static/2024.9/pdf/Cortex Interaction Portal User Guide.pdf new file mode 100644 index 000000000..96a91f213 Binary files /dev/null and b/content/static/2024.9/pdf/Cortex Interaction Portal User Guide.pdf differ diff --git a/content/static/word/CORTEX Interaction Portal - Developer Guide.docx b/content/static/word/CORTEX Interaction Portal - Developer Guide.docx index cee09c9e0..6147feefd 100644 Binary files a/content/static/word/CORTEX Interaction Portal - Developer Guide.docx and b/content/static/word/CORTEX Interaction Portal - Developer Guide.docx differ diff --git a/content/static/word/CORTEX Interaction Portal - Merging Guide.docx b/content/static/word/CORTEX Interaction Portal - Merging Guide.docx index f945699fc..96b915b62 100644 Binary files a/content/static/word/CORTEX Interaction Portal - Merging Guide.docx and b/content/static/word/CORTEX Interaction Portal - Merging Guide.docx differ diff --git a/content/static/word/CORTEX Interaction Portal - Overview.docx b/content/static/word/CORTEX Interaction Portal - Overview.docx index 538be68dd..fd48bb527 100644 Binary files a/content/static/word/CORTEX Interaction Portal - Overview.docx and b/content/static/word/CORTEX Interaction Portal - Overview.docx differ diff --git a/data/urls.toml b/data/urls.toml index ca32d90a3..dd2702193 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -8,6 +8,32 @@ MainDoc = "/blog/releases" [Cortex.Blogs.Releases.2024.X] MainDoc = "/blog/releases/2024.x" + [Cortex.Blogs.Releases.2024.9] + MainDoc = "/blog/2024/10/07/2024.9/" + ProcessAndActivity = "/blog/2024/10/07/2024.9/#process-and-activity" + SaveOutputPropertiesToMultipleVariables = "/blog/2024/10/07/2024.9/#saving-output-properties-to-multiple-variables" + ExecutionContextVariable = "/blog/2024/10/07/2024.9/#execution-context-variable" + ProxyForTheCortex7FlowApi = "/blog/2024/10/07/2024.9/#proxy-for-the-cortex-7-flow-api" + LoggingAddedToBlocksThatCommunicateWithExternalSystems = "/blog/2024/10/07/2024.9/#logging-added-to-blocks-that-communicate-with-external-systems" + ReductionOfTotalNumberOfNServiceBusEndpointsAndRabbitMQQueues = "/blog/2024/10/07/2024.9/#reduction-of-total-number-of-nservicebus-endpoints-and-rabbitmq-queues" + UpgradeOpenSSL = "/blog/2024/10/07/2024.9/#upgrade-openssl" + MultiDomainCertificatesSupport = "/blog/2024/10/07/2024.9/#multi-domain-certificates-support" + NewCortexManagementUserAddedToManageRabbitMQQueues = "/blog/2024/10/07/2024.9/#new-cortexmanagementuser-added-to-manage-rabbitmq-queues" + ServerSideValidationAddedToCortexGatewayAPI = "/blog/2024/10/07/2024.9/#server-side-validation-added-to-cortex-gateway-api" + RemoveRefreshTokenCookieOnSign = "/blog/2024/10/07/2024.9/#remove-refresh-token-cookie-on-sign-out" + RenameFlowsCharmToDevAndChangeIcon = "/blog/2024/10/07/2024.9/#rename-flows-charm-to-dev-and-change-icon" + RenameSettingsCharmToAdminAndChangeIcon = "/blog/2024/10/07/2024.9/#rename-settings-charm-to-admin-and-change-icon" + UpgradeToNet8 = "/blog/2024/10/07/2024.9/#upgrade-to-net-8" + SupportInstallationWhenFilesAreBlockedByTheOperatingSystem = "/blog/2024/10/07/2024.9/#support-installation-when-files-are-blocked-by-the-operating-system" + SupportUpgradeWhenFilesAreBlockedByTheOperatingSystem = "/blog/2024/10/07/2024.9/#support-upgrade-when-files-are-blocked-by-the-operating-system" + ExecutionServiceIsUpgradedWhenTheEngineVersionIsUnchanged = "/blog/2024/10/07/2024.9/#execution-service-is-upgraded-when-the-engine-version-is-unchanged" + HandlingOfTheExecutionServicesLifecycleEvents = "/blog/2024/10/07/2024.9/#handling-of-the-execution-services-lifecycle-events" + ProcessAndActivityDocumentation = "/blog/2024/10/07/2024.9/#process-and-activity-1" + DecompositionOfOutputProperties = "/blog/2024/10/07/2024.9/#decomposition-of-output-properties" + PreventDeadlocksWhenUsingSemaphores = "/blog/2024/10/07/2024.9/#prevent-deadlocks-when-using-semaphores" + ScreenshotsUpdated = "/blog/2024/10/07/2024.9/#screenshots-updated" + FlowCompatibilityVersionIntroduced = "/blog/2024/10/07/2024.9/#flow-compatibility-version-introduced" + GeneralImprovementsToTheDocumentation = "/blog/2024/10/07/2024.9/#general-improvements-to-the-documentation" [Cortex.Blogs.Releases.2024.7] MainDoc = "/blog/2024/08/12/2024.7/" ProductPortal = "/blog/2024/08/12/2024.7/#product-portal" @@ -443,6 +469,8 @@ MainDoc = "/docs/guides/cortex-innovation/core-application/services/execution-management-service/" [Cortex.Guides.CortexInnovation.CoreApplication.Services.LicenceManagementService] MainDoc = "/docs/guides/cortex-innovation/core-application/services/licence-management-service/" + [Cortex.Guides.CortexInnovation.CoreApplication.Services.ListenersService] + MainDoc = "/docs/guides/cortex-innovation/core-application/services/listeners-service/" [Cortex.Guides.CortexInnovation.CoreApplication.Services.PackageManagementService] MainDoc = "/docs/guides/cortex-innovation/core-application/services/package-management-service/" [Cortex.Guides.CortexInnovation.CoreApplication.Services.ProvisioningService] @@ -518,6 +546,23 @@ TryItOut = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/try-it-out" UpgradeApplicationServer = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-application-server" UpgradeWebApplicationServer = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-web-application-server" + [Cortex.Guides.UpgradeCortex.2024.7to2024.9] + MainDoc = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/" + [Cortex.Guides.UpgradeCortex.2024.7to2024.9.Advanced] + UpgradeFlows = "/docs/guides/upgrade-cortex/advanced/upgrade-flows" + [Cortex.Guides.UpgradeCortex.2024.7to2024.9.MultipleServerWithHA] + MainDoc = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/" + TryItOut = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/try-it-out" + UpgradeApplicationAndLoadBalancerServers = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-application-and-loadbalancer-servers" + UpgradeDebugger = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-debugger" + UpgradeGateway = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/upgrade-gateway" + UpgradeWebApplicationServer = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server" + WebApplicationServerPreqrequisites = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/multiple-server-with-ha/upgrade-web-application-server/prerequisites" + [Cortex.Guides.UpgradeCortex.2024.7to2024.9.SingleServerWithoutHA] + MainDoc = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/" + TryItOut = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/try-it-out" + UpgradeApplicationServer = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-application-server" + UpgradeWebApplicationServer = "/docs/guides/upgrade-cortex/2024.7-to-2024.9/single-server-without-ha/upgrade-web-application-server" [Cortex.Guides.UpgradeObservability] MainDoc = "/docs/guides/upgrade-observability/" [Cortex.Guides.UpgradeObservability.OnPremise] @@ -873,11 +918,15 @@ MainDoc = "/docs/reference/blocks/http/execute-http-request" [Cortex.Reference.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequest] MainDoc = "/docs/reference/blocks/http/execute-http-request/execute-http-request-block-1" + HttpRequestProperty = "/docs/reference/blocks/http/execute-http-request/execute-http-request-block-1/#http-request" + HttpResponseProperty = "/docs/reference/blocks/http/execute-http-request/execute-http-request-block-1/#http-response" CallingAnotherFlow = "/docs/reference/blocks/http/execute-http-request/execute-http-request-block-1/#calling-another-flow" [Cortex.Reference.Blocks.Http.ExecuteSoapRequest] MainDoc = "/docs/reference/blocks/http/execute-soap-request" [Cortex.Reference.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequest] MainDoc = "/docs/reference/blocks/http/execute-soap-request/execute-soap-request-block-1" + SoapRequestProperty = "/docs/reference/blocks/http/execute-soap-request/execute-soap-request-block-1/#soap-request" + SoapResponseProperty = "/docs/reference/blocks/http/execute-soap-request/execute-soap-request-block-1/#soap-response" [Cortex.Reference.Blocks.Json] MainDoc = "/docs/reference/blocks/json/" [Cortex.Reference.Blocks.Json.ConvertJson] @@ -1022,6 +1071,10 @@ MainDoc = "/docs/reference/blocks/powershell/execute-powershell-script/" [Cortex.Reference.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScript] MainDoc = "/docs/reference/blocks/powershell/execute-powershell-script/execute-powershell-script-block-1" + ScriptProperty = "/docs/reference/blocks/powershell/execute-powershell-script/execute-powershell-script-block-1/#script" + ParametersProperty = "/docs/reference/blocks/powershell/execute-powershell-script/execute-powershell-script-block-1/#parameters" + OutputsProperty = "/docs/reference/blocks/powershell/execute-powershell-script/execute-powershell-script-block-1/#outputs" + RecordsProperty = "/docs/reference/blocks/powershell/execute-powershell-script/execute-powershell-script-block-1/#records" [Cortex.Reference.Blocks.Queues] MainDoc = "/docs/reference/blocks/queues/" [Cortex.Reference.Blocks.Queues.DequeueItem] @@ -1054,11 +1107,13 @@ MainDoc = "/docs/reference/blocks/ssh/execute-ssh-command" [Cortex.Reference.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock] MainDoc = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block" + CommandProperty = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#command" TerminalPromptMatchRemark = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#using-the-terminalpromptmatch-within-sshlogs-to-reach-the-end-of-a-prompt" ConfigurationSettings = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#configuration-settings" CloseSession = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#close-session" Response = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#response" SshSessionDetails = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#ssh-session-details" + SshLogsProperty = "/docs/reference/blocks/ssh/execute-ssh-command/execute-ssh-command-block/#ssh-logs" [Cortex.Reference.Blocks.Tasks] MainDoc = "/docs/reference/blocks/tasks/" [Cortex.Reference.Blocks.Tasks.CancelTask] @@ -1265,6 +1320,7 @@ Output = "/docs/reference/concepts/fundamentals/blocks/block-properties/what-is-a-block-property/#output-properties" DiscardingOutputs = "/docs/reference/concepts/fundamentals/blocks/block-properties/what-is-a-block-property/#discarding-outputs" InputOutput = "/docs/reference/concepts/fundamentals/blocks/block-properties/what-is-a-block-property/#inputoutput-properties" + DecomposingOutputProperties = "/docs/reference/concepts/fundamentals/blocks/block-properties/what-is-a-block-property/#decomposing-output-properties" [Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties] MainDoc = "/docs/reference/concepts/fundamentals/blocks/block-properties/advanced-properties/" [Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties] @@ -1281,6 +1337,7 @@ MethodExpressions = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#method-expressions" PropertyExpressions = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#property-expressions" IndexExpressions = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#index-expressions" + DecompositionExpressions = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#decomposition-expressions" LiteralValues = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#literal-values" DictionaryLiteral = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#dictionary-literal" ListLiteral = "/docs/reference/concepts/fundamentals/blocks/block-properties/property-editors/expression-editor/#list-literal" @@ -1324,6 +1381,7 @@ MainDoc = "/docs/reference/concepts/fundamentals/executions/" [Cortex.Reference.Concepts.Fundamentals.Executions.WhatIsAnExecution] MainDoc = "/docs/reference/concepts/fundamentals/executions/what-is-an-execution" + ExecutionContext = "/docs/reference/concepts/fundamentals/executions/what-is-an-execution/#execution-context" [Cortex.Reference.Concepts.Fundamentals.Executions.ExecutionsInDevelopment] MainDoc = "/docs/reference/concepts/fundamentals/executions/executions-in-development" EditAndContinueAnExecution = "/docs/reference/concepts/fundamentals/executions/executions-in-development/#edit-and-continue-an-execution" @@ -1341,6 +1399,8 @@ MainDoc = "/docs/reference/concepts/fundamentals/flows/handling-exceptions-within-a-flow" [Cortex.Reference.Concepts.Fundamentals.Flows.WhatIsAFlow] MainDoc = "/docs/reference/concepts/fundamentals/flows/what-is-a-flow" + Process = "/docs/reference/concepts/fundamentals/flows/what-is-a-flow/#process" + Activity = "/docs/reference/concepts/fundamentals/flows/what-is-a-flow/#activity" [Cortex.Reference.Concepts.Fundamentals.Messages] MainDoc = "/docs/reference/concepts/fundamentals/messages/" [Cortex.Reference.Concepts.Fundamentals.Messages.WhatIsAMessage] @@ -1397,6 +1457,7 @@ Non-Queuing = "/docs/reference/concepts/working-with/concurrency/semaphores/what-is-a-semaphore/#non-queuing-semaphore" Queuing = "/docs/reference/concepts/working-with/concurrency/semaphores/what-is-a-semaphore/#queuing-semaphore" MultipleConcurrencyLimits = "/docs/reference/concepts/working-with/concurrency/semaphores/what-is-a-semaphore/#multiple-concurrency-limits" + PreventingDeadlocks = "/docs/reference/concepts/working-with/concurrency/semaphores/what-is-a-semaphore/#preventing-deadlocks" [Cortex.Reference.Concepts.WorkingWith.Culture] MainDoc = "/docs/reference/concepts/working-with/culture/" [Cortex.Reference.Concepts.WorkingWith.Culture.CurrentCulture] @@ -2729,6 +2790,9 @@ BlockStatement = "https://blogs.oracle.com/connect/post/building-with-blocks" [OracleParameter] ParameterDirection = "https://learn.microsoft.com/en-us/dotnet/api/system.data.parameterdirection?view=net-8.0" +[Owasp] + [Owasp.PathTraversal] + MainDoc = "https://owasp.org/www-community/attacks/Path_Traversal" [Particular] [Particular.NServiceBus] MainDoc = "https://particular.net/nservicebus"