Merge pull request #113381 from BethWilke/branch128

Finalizing changes for 1708447

Author: American-Dipper

articles/automation/automation-connections.md

@@ -15,7 +15,7 @@ An Azure Automation connection asset contains the information listed below. This
 * Information needed for authentication, such as user name and password
 * Connection information, such as URL or port
 
-The connection asset keeps all properties for connecting to a particular application together, making it unnecessary to create multiple variables. You can edit the values for a connection in one place, and you can pass the name of a connection to a runbook or DSC configuration in a single parameter. The runbook or configuration accesses the properties for a connection using the internal `Get-AutomationConnection` cmdlet.
+The connection asset keeps together all properties for connecting to a particular application, making it unnecessary to create multiple variables. You can edit the values for a connection in one place, and you can pass the name of a connection to a runbook or DSC configuration in a single parameter. The runbook or configuration accesses the properties for a connection using the internal `Get-AutomationConnection` cmdlet.
 
 When you create a connection, you must specify a connection type. The connection type is a template that defines a set of properties. You can add a connection type to Azure Automation using an integration module with a metadata file. It's also possible to create a connection type using the [Azure Automation API](/previous-versions/azure/reference/mt163818(v=azure.100)) if the integration module includes a connection type and is imported into your Automation account. 
 
@@ -27,17 +27,17 @@ When you create a connection, you must specify a connection type. The connection
 
 ## Connection types
 
-Azure Automation makes the following built-in connections available:
+Azure Automation makes the following built-in connection types available:
 
-* `Azure` - This connection can be used to manage classic resources.
-* `AzureServicePrincipal` - This connection is used by the Azure Run As account.
-* `AzureClassicCertificate` - This connection is used by the classic Azure Run As account.
+* `Azure` - Represents a connection used to manage classic resources.
+* `AzureServicePrincipal` - Represents a connection used by the Azure Run As account.
+* `AzureClassicCertificate` - Represents a connection used by the classic Azure Run As account.
 
 In most cases, you don't need to create a connection resource because it is created when you create a [Run As account](manage-runas-account.md).
 
-## Windows PowerShell cmdlets
+## Windows PowerShell cmdlets to access connections
 
-The cmdlets in the following table are used to create and manage Automation connections with Windows PowerShell. They ship as part of the Az module. See [Manage modules in Azure Automation](shared-resources/modules.md).
+The cmdlets in the following table create and manage Automation connections with Windows PowerShell. They ship as part of the [Az modules](shared-resources/modules.md#az-modules).
 
 |Cmdlet|Description|
 |---|---|
@@ -46,18 +46,18 @@ The cmdlets in the following table are used to create and manage Automation conn
 |[Remove-AzAutomationConnection](https://docs.microsoft.com/powershell/module/Az.Automation/Remove-AzAutomationConnection?view=azps-3.7.0)|Removes an existing connection.|
 |[Set-AzAutomationConnectionFieldValue](https://docs.microsoft.com/powershell/module/Az.Automation/Set-AzAutomationConnectionFieldValue?view=azps-3.7.0)|Sets the value of a particular field for an existing connection.|
 
-## Internal cmdlets
+## Internal cmdlets to access connections
 
 The internal cmdlet in the following table is used to access connections in your runbooks and DSC configurations. This cmdlet comes with the global module `Orchestrator.AssetManagement.Cmdlets`. For more information, see [Internal cmdlets](shared-resources/modules.md#internal-cmdlets).
 
 |Internal Cmdlet|Description|
 |---|---|
-|`Get-AutomationConnection` | Retrieves the values of the different fields in the connection and returns them as a [hashtable](https://go.microsoft.com/fwlink/?LinkID=324844). This hashtable can then be used with the appropriate commands in the runbook or DSC configuration.|
+|`Get-AutomationConnection` | Retrieves the values of the different fields in the connection and returns them as a [hashtable](https://go.microsoft.com/fwlink/?LinkID=324844). You can then use this hashtable with the appropriate commands in the runbook or DSC configuration.|
 
 >[!NOTE]
->Avoid using variables with the `Name` parameter of `Get-AutomationConnection`. Use of this parameter can complicate discovery of dependencies between runbooks or DSC configurations and connection assets at design time.
+>Avoid using variables with the `Name` parameter of `Get-AutomationConnection`. Use of variables in this case can complicate discovery of dependencies between runbooks or DSC configurations and connection assets at design time.
 
-## Python 2 functions
+## Python 2 functions to access connections
 
 The function in the following table is used to access connections in a Python 2 runbook.
 
@@ -68,7 +68,7 @@ The function in the following table is used to access connections in a Python 2
 > [!NOTE]
 > You must import the `automationassets` module at the top of your Python runbook to access the asset functions.
 
-## Creating a new connection
+## Create a new connection
 
 ### Create a new connection with the Azure portal
 
@@ -91,13 +91,13 @@ $ConnectionFieldValues = @{"ApplicationId" = $Application.ApplicationId; "Tenant
 New-AzAutomationConnection -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccountName -Name $ConnectionAssetName -ConnectionTypeName AzureServicePrincipal -ConnectionFieldValues $ConnectionFieldValues
 ```
 
-When you create your Automation account, it includes several global modules by default, along with the connection type `AzureServicePrincipal` to create the `AzureRunAsConnection` connection asset. If you try to create a new connection asset to connect to a service or application with a different authentication method, the operation fails because the connection type is not already defined in your Automation account. For more information on creating your own connection type for a custom module, see [Adding a connection type](#adding-a-connection-type).
+When you create your Automation account, it includes several global modules by default, along with the connection type `AzureServicePrincipal` to create the `AzureRunAsConnection` connection asset. If you try to create a new connection asset to connect to a service or application with a different authentication method, the operation fails because the connection type is not already defined in your Automation account. For more information on creating your own connection type for a custom module, see [Add a connection type](#add-a-connection-type).
 
-## Adding a connection type
+## Add a connection type
 
-If your runbook or DSC configuration connects to an external service, you must define a connection type in a [custom module](shared-resources/modules.md#custom-modules), called an integration module. This file specifies connection type properties and is named **<ModuleName>-Automation.json**, located in the module folder of your compressed **.zip** file. This file contains the fields of a connection that are required to connect to the system or service the module represents. Using this file, you can set the field names, data types, encryption status, and optional status for the connection type. 
+If your runbook or DSC configuration connects to an external service, you must define a connection type in a [custom module](shared-resources/modules.md#custom-modules) called an integration module. This module includes a metadata file that specifies connection type properties and is named **<ModuleName>-Automation.json**, located in the module folder of your compressed **.zip** file. This file contains the fields of a connection that are required to connect to the system or service that the module represents. Using this file, you can set the field names, data types, encryption status, and optional status for the connection type. 
 
-The following example is a template in the **.json** file format that defines user name and password properties for a custom connection type:
+The following example is a template in the **.json** file format that defines user name and password properties for a custom connection type called `MyModuleConnection`:
 
 ```json
 {
@@ -120,32 +120,32 @@ The following example is a template in the **.json** file format that defines us
 }
 ```
 
-## Using a connection in a runbook or DSC configuration
+## Get a connection in a runbook or DSC configuration
 
-Retrieve a connection in a runbook or DSC configuration with the internal `Get-AutomationConnection` cmdlet. This cmdlet is preferred over the `Get-AzAutomationConnection` cmdlet. See [Internal cmdlets](shared-resources/modules.md#internal-cmdlets).
+Retrieve a connection in a runbook or DSC configuration with the internal `Get-AutomationConnection` cmdlet. This cmdlet is preferred over the `Get-AzAutomationConnection` cmdlet, as it retrieves the connection values instead of information about the connection. 
 
-### Textual runbook sample
+### Textual runbook example
 
-The following sample commands show how to use the Run As account to authenticate with Azure Resource Manager resources in your runbook. It uses the connection asset representing the Run As account, which references the certificate-based service principal.
+The following example shows how to use the Run As account to authenticate with Azure Resource Manager resources in your runbook. It uses a connection asset representing the Run As account, which references the certificate-based service principal.
 
 ```powershell
 $Conn = Get-AutomationConnection -Name AzureRunAsConnection
 Connect-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint
 ```
 
-### Graphical runbook samples
+### Graphical runbook examples
 
-You add a `Get-AutomationConnection` activity to a graphical runbook by right-clicking on the connection in the Library pane of the graphical editor and selecting **Add to canvas**.
+You can add an activity for the internal `Get-AutomationConnection` cmdlet to a graphical runbook. Right-click the connection in the Library pane of the graphical editor and select **Add to canvas**.
 
 ![add to canvas](media/automation-connections/connection-add-canvas.png)
 
-The following image shows an example of using a connection in a graphical runbook. This example uses the `Constant value` data set for the `Get RunAs Connection` activity that uses a connection object for authentication. A [pipeline link](automation-graphical-authoring-intro.md#links-and-workflow) is used here since the `ServicePrincipalCertificate` parameter set is expecting a single object.
+The following image shows an example of using a connection object in a graphical runbook. This example uses the `Constant value` data set for the `Get RunAs Connection` activity, which uses a connection object for authentication. A [pipeline link](automation-graphical-authoring-intro.md#links-and-workflow) is used here since the `ServicePrincipalCertificate` parameter set is expecting a single object.
 
 ![get connections](media/automation-connections/automation-get-connection-object.png)
 
-### Python 2 runbook sample
+### Python 2 runbook example
 
-The following sample shows how to authenticate using the Run As connection in a Python 2 runbook.
+The following example shows how to authenticate using the Run As connection in a Python 2 runbook.
 
 ```python
 """ Tutorial to show how to authenticate against Azure resource manager resources """
@@ -190,6 +190,6 @@ azure_credential = get_automation_runas_credential(runas_connection)
 
 ## Next steps
 
-- Review [Links in graphical authoring](automation-graphical-authoring-intro.md#links-and-workflow) to understand how to direct and control the flow of logic in your runbooks.
-* For a PowerShell cmdlet reference, see [Az.Automation](https://docs.microsoft.com/powershell/module/az.automation/?view=azps-3.7.0#automation
-).
+* To learn more about the cmdlets used to access connections, see [Manage modules in Azure Automation](shared-resources/modules.md).
+* For general information about runbooks, see [Runbook execution in Azure Automation](automation-runbook-execution.md).
+* For details of DSC configurations, see [State Configuration overview](automation-dsc-overview.md).

articles/automation/shared-resources/certificates.md

@@ -21,19 +21,20 @@ Certificates are stored securely in Azure Automation for access by runbooks and
 >[!NOTE]
 >This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see [Introducing the new Azure PowerShell Az module](https://docs.microsoft.com/powershell/azure/new-azureps-module-az?view=azps-3.5.0). For Az module installation instructions on your Hybrid Runbook Worker, see [Install the Azure PowerShell Module](https://docs.microsoft.com/powershell/azure/install-az-ps?view=azps-3.5.0). For your Automation account, you can update your modules to the latest version using [How to update Azure PowerShell modules in Azure Automation](../automation-update-azure-modules.md).
 
-## Az PowerShell cmdlets
+## Windows PowerShell cmdlets to access certificates
 
-For Az, the cmdlets in the following table are used to create and manage automation credential assets with Windows PowerShell. They ship as part of the [Az.Automation module](/powershell/azure/overview), which is available for use in Automation runbooks and DSC configurations.
+The cmdlets in the following table create and manage Automation certificates with Windows PowerShell. They ship as part of the [Az modules](modules.md#az-modules).
 
 |Cmdlet |Description|
 | --- | ---|
-|[Add-AzureCertificate](/powershell/module/servicemanagement/azure/add-azurecertificate)|Uploads a service certificate for the specified cloud service.|
 |[Get-AzAutomationCertificate](https://docs.microsoft.com/powershell/module/Az.Automation/Get-AzAutomationCertificate?view=azps-3.7.0)|Retrieves information about a certificate to use in a runbook or DSC configuration. You can only retrieve the certificate itself using the internal `Get-AutomationCertificate` cmdlet.|
 |[New-AzAutomationCertificate](https://docs.microsoft.com/powershell/module/Az.Automation/New-AzAutomationCertificate?view=azps-3.7.0)|Creates a new certificate in Azure Automation.|
 |[Remove-AzAutomationCertificate](https://docs.microsoft.com/powershell/module/Az.Automation/Remove-AzAutomationCertificate?view=azps-3.7.0)|Removes a certificate from Azure Automation.|
 |[Set-AzAutomationCertificate](https://docs.microsoft.com/powershell/module/Az.Automation/Set-AzAutomationCertificate?view=azps-3.7.0)|Sets the properties for an existing certificate including uploading the certificate file and setting the password for a **.pfx** file.|
 
-## Internal cmdlets
+The [Add-AzureCertificate](/powershell/module/servicemanagement/azure/add-azurecertificate) cmdlet can also be used to upload a service certificate for the specified cloud service.
+
+## Internal cmdlets to access certificates
 
 The internal cmdlet in the following table is used to access certificates in your runbooks. This cmdlet comes with the global module `Orchestrator.AssetManagement.Cmdlets`. For more information, see [Internal cmdlets](modules.md#internal-cmdlets).
 
@@ -44,7 +45,7 @@ The internal cmdlet in the following table is used to access certificates in you
 > [!NOTE] 
 > You should avoid using variables in the `Name` parameter of `Get-AutomationCertificate` in a runbook or DSC configuration. Use of variables in this parameter can complicate discovery of dependencies between runbooks or DSC configurations and Automation variables at design time.
 
-## Python 2 functions
+## Python 2 functions to access certificates
 
 The function in the following table is used to access certificates in a Python 2 runbook.
 
@@ -55,7 +56,7 @@ The function in the following table is used to access certificates in a Python 2
 > [!NOTE]
 > You must import the `automationassets` module at the beginning of your Python runbook to access the asset functions.
 
-## Creating a new certificate
+## Create a new certificate
 
 When you create a new certificate, you upload a .cer or .pfx file to Azure Automation. If you mark the certificate as exportable, then you can transfer it out of the Azure Automation certificate store. If it isn't exportable, then it can only be used for signing within the runbook or DSC configuration. Azure Automation requires the certificate to have the provider **Microsoft Enhanced RSA and AES Cryptographic Provider**.
 
@@ -124,7 +125,7 @@ $json | out-file .\template.json
 New-AzResourceGroupDeployment -Name NewCert -ResourceGroupName TestAzureAuto -TemplateFile .\template.json
 ```
 
-## Using a certificate
+## Get a certificate
 
 To retrieve a certificate, use the internal `Get-AutomationCertificate` cmdlet. You can't use the [Get-AzAutomationCertificate](https://docs.microsoft.com/powershell/module/Az.Automation/Get-AzAutomationCertificate?view=azps-3.7.0) cmdlet, since it returns information about the certificate asset but not the certificate itself.
 
@@ -164,4 +165,6 @@ print cert
 
 ## Next steps
 
-- To learn more about working with links to control the logical flow of activities in your graphical runbook, see [Links in graphical authoring](../automation-graphical-authoring-intro.md#links-and-workflow). 
+* To learn more about the cmdlets used to access certificates, see [Manage modules in Azure Automation](modules.md).
+* For general information about runbooks, see [Runbook execution in Azure Automation](../automation-runbook-execution.md).
+* For details of DSC configurations, see [State Configuration overview](../automation-dsc-overview.md).