Migrate BuildMaster legacy features docs from KB and ocnvert to markdown

BuildMaster/installation-and-maintenance/legacy-features.md

@@ -0,0 +1,172 @@
+---
+title: Legacy Features
+subtitle: BuildMaster Legacy Features
+keywords: buildmaster, legacy
+sequence: 900
+show-headings-in-nav: true
+---
+
+With the inclusion of the [Inedo Execution Engine](/support/documentation/buildmaster/execution-engine/overview) and [the Inedo Agent](/support/documentation/various/inedo-agent/the-agent) in BuildMaster v5, several existing features were replaced with newer features that were a better fit for the new model. We consider these since-rebuilt features to be "legacy features", and this document will describe the impact of using these features as well as migration guidance to a non-legacy method.
+
+Note that most unused legacy features are hidden from the user interface in order to prevent unintended usage on newer installations; depending on when you first started using BuildMaster, you may not see these features at all.
+
+## Legacy Features Index
+
+| Legacy Feature | Replacement Feature | |
+|---|---|---|
+| Deployment Plans | OtterScript Plans | [learn more](#plans) |
+| TCP/IIS Agents | Inedo Agent | [learn more](#agents) |
+| Server Groups | Server Roles | [learn more](#server-groups) |
+| Server Pools | Server Roles & Resource Pools | [learn more](#server-pools) |
+| Extension Configuration/Profiles | Configuration Variables & Resource Credentials | [learn more](#extension-configurations) |
+| Build Importers | OtterScript Plans & Tool-specific Operations | [learn more](#build-importers) |
+| Source Control Providers | Resource Credentials & Tool-specific Operations | [learn more](#source-control-providers) |
+| Issue Tracking Providers | Resource Credentials & Issue Sources | [learn more](#issue-tracking-providers) |
+| Issue + Build Association | Automatically Change Issue Status | [learn more](#issues-and-builds) |
+| Legacy Configuration Variables | Multi-scope Configuration Variables | [learn more](#variables) |
+| Legacy Template Variables | Release Templates | [learn more](#template-variables) |
+| PowerShell/Shell Scripts | Script Assets | [learn more](#scripts) |
+| Change Controls | Issues, Release Notes, or Otter | [learn more](#change-controls) |
+| Variable %-syntax | OtterScript Variable $-syntax | [learn more](#variable-syntax) |
+
+## Best practice: migrate, but over time...
+
+Generally speaking, you should plan to migrate from using legacy features. In addition to being less performant, less usable, and with less-defined behaviors, legacy features become harder to support -- both internally (i.e. BuildMaster users supporting their users) and externally (our support team).
+
+However, this doesn't need to happen right away. These legacy features will be maintained indefinitely, likely through the end of the product line. Instead, come up with a migration plan that allows you to migrate away from legacy features with minimal business risk; for example, when you need to make changes to an application or deployment plan, you should plan to migrate the legacy feature as well.
+
+## The Legacy Features Dashboard
+
+As of BuildMaster 5.8, the Legacy Feature Dashboard will be a page within BuildMaster that will provide an overview of any legacy features that are being used in an existing installation of BuildMaster, and link to this page with migration guidance. For some legacy features, migration can be handled automatically from the Legacy Feature Dashboard.
+
+### Legacy Plans => OtterScript Plans
+
+OtterScript-based Plans are used by the new execution engine; this is a complete rewrite and takes into account years of experience supporting complex, multi-server orchestrations with easy-to-use deployment plans, and incorporates a tremendous amount of technological advancements, including features such as: locking, iteration, asynchronous operation blocks, textual representation, versioning, template parsing, and more.
+
+See [KB#118 (Legacy Plans in BuildMaster)](/support/kb/1118) for more information and a migration strategy.
+
+### Agents => Inedo Agent
+
+The Inedo Agent was designed from the ground-up, using years of experience from the Legacy Agents, to support multiple products using a secure, lightweight, highly-optimized, and resilient protocol. See [KB#1039 - The Inedo Agent and Legacy BuildMaster Agents](/support/kb/1039) for more information and migration strategy.
+
+### Server Groups => Server Roles
+
+Server groups were the only way to deploy to multiple servers with a single action in a legacy deployment plan. OtterScript makes deployment in this manner trivial with [iteration blocks](/support/documentation/buildmaster/execution-engine/statements-and-blocks/loop), so there is no longer a need for server groups.
+
+#### Migration Strategy
+
+If you have existing server groups, you can run the Server Group Migration tool from the Legacy Features Dashboard. This will create a matching Server Role for every Server Group in the system and assign the same servers to it if possible, or will log an error with instructions detailing which server group failed to convert.
+
+### Server Pools => Resource Pools
+
+Server pools were used to prevent more than one deployment action running on a specific server at a time. This functionality is replaced by the Acquire-Server operation in conjunction with Server Roles.
+
+#### Migration Strategy
+
+Existing server pools can be converted to Server Roles with the Server Group Migration tool. Deployment plans that refer to a server pool should be changed to use the Acquire-Server operation whenever exclusivity of a server is required, e.g.
+
+```
+Acquire-Server
+( 
+    Role: build-servers,
+    ServerName => $AcquiredServerName
+);
+```
+
+and then use the `$AcquiredServerName` in a `for server` context as needed. The acquired server will be released at the end of the execution, or earlier if the Release-Server operation is used.
+
+### Extension Configuration => Extension Configuration Variables or Resource Credentials
+
+Extension configurers were used to configure extensions and provide defaults for common values (e.g. Windows SDK path) used system-wide, and also for common values needed outside the scope of a legacy plan execution (e.g. build importer UI). The primary benefit of the extension configuration variables is that they may be declared at any configuration variable scope. Using $MSBuildToolsPath in the WindowsSDK extension as an example, different configuration variables can be configured at the server level for different build servers and any builds/deployments performed in that server will use its specified MSBuild Tools Path instead of having to override it at the operation level.
+
+#### Migration Strategy
+
+Existing configurers must be converted on an individual basis because sometimes there is not a 1-1 mapping. Visiting the "Configuration" tab on the Extension Overview page will show any values which can be supplied. Note that unlike extension configuration, these values are almost never required and a "best guess" or lookup is done if not set. If for some reason a configuration value is required and not automatically deduced, any operations that require a value will fail and report the missing value as an error in the execution log.
+
+### Build Importers => Operations
+
+Build importers were used primarily to pull an artifact into BuildMaster from a Continuous Integration tool like TeamCity, Jenkins, or package manager like NuGet. With the v5 Execution Engine, this is duplicative of what can be done generally with a single operation.
+
+#### Migration Strategy
+
+The specific migration strategy depends on the importer, but the basic idea is to create a plan, and add one (or more) of the following operations to reproduce the behavior of the importer:
+
+{.docs}
+ - `TeamCity::Queue-Build`
+ - `TeamCity::Import-Artifact`
+ - `TFS::Queue-Build`
+ - `TFS::Download-Artifact`
+ - `Jenkins::Queue-Build`
+ - `Jenkins::Download-Artifact`
+
+### Source Control Providers => Resource Credentials and Tool-Specific Operations
+
+Source control providers were used to specify source control server connection information in a single location and to abstract the experience of adding deployment plan actions no matter what source control system was used. This abstraction was both unnecessary and leaky, primarily because different systems have different workflows (e.g. SVN vs Git). The source control specific operations are the replacement for the Get Latest, Get Latest, and Apply Tag family of actions.
+
+Any source control operations may accept the full connection and repository information (either inline or in a Resource Credential), so having the providers becomes duplicative once again.
+
+#### Migration Strategy
+
+Switching to these operations obviously requires legacy plans to be converted, and then Resource Credentials to be created for each provider or repository in the case of SVN which allows multiple repositories to be defined in a single provider. It's helpful to first take note of what operation properties are available for the specific source control system. As an example, the Git::Git-GetSource operation allows the specification of a repository URL, target disk path, branch or tag name, and credentials to connect. The values for these properties will become obvious from the saved data in the provider and Get Latest action, e.g. "Source directory" becomes "target disk path", "Remote URL" becomes "repository URL", and so on.
+
+### Issue Tracking Providers => Issue Sources and Tool-Specific Operations
+
+Issue tracking providers, like source control providers, were used to specify connection information to an issue tracker (e.g. JIRA, YouTrack) and abstract integration points (e.g. Create Issue, Append Comment). Also like source control providers, this abstraction is leaky and overly complex. Issue Sources are unique per tool, and unlike issue tracking providers, can accept variables in their tool-specific properties simplifying configuration within BuildMaster.
+
+#### Migration Strategy
+
+Generally, an issue source should be created for each issue tracking provider. Issue tracking providers required configuration at the application level that filtered the retrieved issues. Because issue sources accept variables, this can be done at the system level instead. As an example, the YouTrack issue source can be configured with "Project name" and "Fix version". Values of $ApplicationName and $ReleaseName means that any issues associated with a BuildMaster application whose release name (or number if none specified) matches the fix version will be pulled from YouTrack and displayed on that application's release overview page.
+
+If an issue source is unique to a specific application (i.e. the "Marketing" website is the only project that uses JIRA for issues), it can be defined at the application level on the application settings page.
+
+### Association of Issues and Builds
+
+Issues are always associated with a release, and in BuildMaster 6.1 and earlier, they may also be associated with up to two builds: Opened (the first build that BuildMaster spotted the issue) and Closed (the first build that BuildMaster noticed the issue was resolved). This feature was primarily intended to help QA identify when they could start testing changes. However, the ability to [Automatically Change Issue Status](/docs/buildmaster/applications/issue-tracking#changing-issue-status) is a better way to notify QA, much more intuitive, and simpler for all.
+
+### Legacy Variables => Configuration Variables
+
+See [KB#1128 (Legacy Variables)](/support/kb/1128) for more information.
+
+### Legacy Template Variables (Release, Build, Execution, Promotion) => Release Templates
+
+Legacy template variables were used to specify variables and optionally default values for releases, builds, and executions/promotions (now just deployments). The new method to handle variable prompts during release, package, or deployment time is release templates.
+
+Release templates act as an initial template rather than a "default" or "fallback", separating the concern of the variable values from their specification in the application settings. Once a release or package is created via template, release and package variables are created as necessary, and their values can be edited on an individual basis from the release or package page. Deployment variable values are injected as Runtime Variable values and cannot be changed since they are specific to a single deployment.
+
+#### Migration Strategy
+
+Converting legacy template variables requires inspecting the Legacy Template Variables page and copying those values into a new release template. In cases where an application has a single release template, it will be used as the default for all created releases maintaining the same behavior held by the legacy template variables (which applied to all releases).
+
+Legacy template variables could have various restrictions (e.g. numbers only, dropdown lists) or could be derived from external sources (e.g. TeamCity Build Number). This functionality is replicated by the "Dynamic List" release template variable, and extended by allowing other options (such as multiple selections, restricting values, obscuring values, etc.)
+
+### Percent Variable Syntax => OtterScript Variable Syntax
+
+In previous versions, variables were referenced like Batch script variables by surrounding them with % signs (i.e. `%RELNO%` for release number). That syntax was deprecated in favor of the $ syntax (i.e. `$ReleaseNumber`). While syntactically similar to OtterScript variable syntax which also uses the $ sign, the escaping rules were different (`$$VarName` evaluates to literal `$VarName`). This would generate an error when parsed by the OtterScript Execution Engine where the escape character is the backtick (i.e. <code>`$VarName</code>).
+
+#### Migration Strategy
+
+Migrating the variable syntaxes is rarely required if the % syntax was never used, since the primary difference is the escape character changing from `$` to <code>\`</code>. However, all uses of `%VARNAMES%` must be converted to `$VarName` or `${LongerNameWith.Chars}` if there are non-alphanumeric characters present in the name. Beyond alphanumeric characters, only the "_" (underscore), "-" (dash), "." (period), and " " (space) characters are permitted to be used in variable names. Any other characters will result in a runtime error when parsing the variable names.
+
+For configuration files, you can use the migration tool within BuildMaster to automatically perform the conversion.
+
+### Legacy PowerShell and Shell Scripts => PowerShell and Shell Script Assets
+
+Legacy scripts were scripts accessible from any deployment plan. They are replaced by Script Assets, which may be stored at the system or application level. Script assets do not require parameters to be specified within BuildMaster, they are automatically parsed from built-in help comments explained here: [https://technet.microsoft.com/en-us/library/ff458353.aspx](https://technet.microsoft.com/en-us/library/ff458353.aspx). "Ambient variables" are replaced by supplying the variables directly as arguments to the operation.
+
+#### Migration Strategy
+
+Migrating scripts can be done at the system level by running the Legacy Script Migration Tool on the Legacy Features Dashboard. This will essentially perform a copy/paste of the script contents into the new format. To consume the scripts, adding a PsCall or ShCall operation for PowerShell or Shell scripts respectively to a deployment plan will execute the script at deployment time. If a script is only used by a single application, it is recommended to add it as a Script Asset to that specific application to reduce system-wide clutter and prevent it from appearing in the plan editor for other applications unnecessarily.
+
+### Change Controls => Issues & Release Notes
+
+Change controls were essentially a checklist designed to keep track of "occurrences" performed in a specific environment per release. With the advent of pipelines, change controls became less effective since promotions occurred through stages instead of environments, and ultimately replaceable by any issue tracker (including BuildMaster's built-in one) since those already handle complete/incomplete status per release based on whether the issue is closed or not.
+
+Current customers using change controls may switch to using [Issues or Notes](/support/documentation/buildmaster/modeling-applications/issues-notes) going forward. One of the main use cases for change controls was to mimic server provisioning (e.g. setting up services, app pools, etc.), it is also worth investigating [Otter](/otter) as a fully automated replacement.
+
+### Day/Time-based Promotion Requirement => Deployment Windows
+
+For deployments that must occur within a certain time window, Deployment Windows should be used in favor of the legacy day/time-based promotion requirement. Multiple deployment windows can be specified for a single pipeline stage in addition to an optional time zone for global deployments. Additionally, more context is shown for deployment windows when deployment is forbidden.
+
+#### Migration Strategy
+
+Conversion to Deployment Windows should be done manually, and should be a straightforward 1:1 matchup of properties.