Edit

Share via

Add and run PowerShell script code in Standard workflows for Azure Logic Apps (Preview)

  • Article

Applies to: Azure Logic Apps (Standard)

Note

This capability is in preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.

To perform custom integration tasks inline with your Standard workflow in Azure Logic Apps, you can directly add and run PowerShell code from within your workflow. For this task, use the Inline Code action named Execute PowerShell Code. This action returns the results from your PowerShell code so that you can use this output in your workflow's subsequent actions.

This capability provides the following benefits:

  • Write your own scripts within the workflow designer so you can solve complex integration challenges. No other service plans are necessary.

    This benefit streamlines workflow development plus reduces the complexity and cost with managing more services.

  • Generate a dedicated code file, which provides a personalized scripting space within your workflow.

  • Integrate with Azure Functions PowerShell Functions, which provides powerful functionality and inheritance for advanced task execution.

  • Deploy scripts alongside your workflows.

This guide shows how to add the action in your workflow and add the PowerShell code that you want to run.

Prerequisites

  • An Azure account and subscription. If you don't have a subscription, sign up for a free Azure account.

  • The Standard logic app workflow where you want to add your PowerShell script. The workflow must already start with a trigger. For more information, see Create example Standard logic app workflows.

    You can use any trigger for your scenario, but as an example, this guide uses the Request trigger named When a HTTP request is received and also the Response action. The workflow runs when another application or workflow sends a request to the trigger's endpoint URL. The sample script returns the results from code execution as output that you can use in subsequent actions.

Considerations

  • The Azure portal saves your script as a PowerShell script file (.ps1) in the same folder as your workflow.json file, which stores the JSON definition for your workflow, and deploys the file to your logic app resource along with the workflow definition.

    The .ps1 file format lets you write less "boilerplate" and focus just on writing PowerShell code. If you rename the action, the file is also renamed, but not vice versa. If you directly rename the file, the renamed version overwrites the previous version. If the action name and file names don't match, the action can't find the file and tries to create a new empty file.

  • The script is local to the workflow. To use the same script in other workflows, view the script file in the KuduPlus console, and then copy the script to reuse in other workflows.

Limitations

Name Limit Notes
Script run duration 10 minutes If you have scenarios that need longer durations, use the product feedback option to provide more information about your needs.
Output size 100 MB Output size depends on the output size limit for actions, which is generally 100 MB.

Add the Execute PowerShell Code action

  1. In the Azure portal, open your Standard logic app resource and workflow in the designer.

  2. In the designer, follow these general steps to add the Inline Code Operations action named Execute PowerShell Code to your workflow.

  3. After the action information pane opens, on the Parameters tab, in the Code File box, update the prepopulated sample code with your own code.

    The following example shows the action's Parameters tab with the sample script code:

    Screenshot shows Azure portal, Standard workflow designer, Request trigger, Execute PowerShell Code action with information pane open, and Response action. Information pane shows sample PowerShell script.

    The following example shows the sample script code:

    # Use the following cmdlets to retrieve outputs from prior steps.
# $triggerOutput = Get-TriggerOutput
# $ActionOutput = Get-ActionOutput -ActionName <action-name>

$customResponse =  [PSCustomObject]@{
   Message = "Hello world!"
}

# Use Write-Debug/Write-Host/Write-Output/ to log messages to Application Insights.
# Write-Host/Write-Output/Write-Debug and 'return' won't return an output to the workflow.
# Write-Host "Sending to Application Insight logs"

# Use Push-WorkflowOutput to push outputs into subsequent actions.
Push-WorkflowOutput -Output $customResponse

    The following example shows a custom sample script:

    $action = Get-TriggerOutput
$results = "Hello from PowerShell!"
Push-WorkflowOutput -Output $results

  4. When you finish, save your workflow.

After you run your workflow, you can review the workflow output in Application Insights, if enabled. For more information, see View output in Application Insights.

Access workflow trigger and action outputs in your script

The output values from the trigger and preceding actions are returned using a custom object, which has multiple parameters. To access these outputs and make sure that you return the value that you want, use the Get-TriggerOutput, Get-ActionOutput, and Push-WorkflowOutput cmdlets plus any appropriate parameters described in the following table, for example:

$trigger = Get-TriggerOutput
$statusCode = $trigger.status.ToString();
$action = Get-ActionOutput -ActionName Compose
$actionOutput = $action.outputs['actionOutput'].ToString();
$populatedString = "Send the $statusCode for the trigger status and $actionOutputName."

Push-WorkflowOutput -Output $populatedString

Note

In PowerShell, if you reference an object that has JValue type inside a complex object, and you add that object to a string, you get a format exception. To avoid this error, use ToString().

Trigger and action response outputs

The following table lists the outputs that are generated when you call Get-ActionOutput or Get-TriggerOutput. The return value is a complex object called PowershellWorkflowOperationResult, which contains thee following outputs.

Name Type Description
Name String The name for the trigger or action.
Inputs JToken The input values passed into the trigger or action.
Outputs JToken The outputs from the executed trigger or action.
StartTime DateTime The start time for the trigger or action.
EndTime DateTime The end time for the trigger or action.
ScheduledTime DateTime The scheduled time to run the trigger or action or trigger.
OriginHistoryName String The origin history name for triggers with the Split-On option enabled.
SourceHistoryName String The source history name for a resubmitted trigger.
TrackingId String The operation tracking ID.
Code String The status code for the result.
Status String The run status for the trigger or action, for example, Succeeded or Failed.
Error JToken The HTTP error code.
TrackedProperties JToken Any tracked properties that you set up.

Return outputs to your workflow

To return any outputs to your workflow, you must use the Push-WorkflowOutput cmdlet.

Custom PowerShell commands

The Execute PowerShell Code action includes following custom PowerShell commands (cmdlets) for interacting with your workflow and other operations in your workflow:

Get-TriggerOutput

Gets the output from the workflow's trigger.

Syntax

Get-TriggerOutput

Parameters

None.

Get-ActionOutput

Gets the output from another action in the workflow and returns an object named PowershellWorkflowOperationResult.

Syntax

Get-ActionOutput [ -ActionName <String> ]

Parameters

Parameter Type Description
ActionName String The name of the action in the workflow with the output that you want to reference.

Push-WorkflowOutput

Pushes output from the Execute PowerShell Code action to your workflow, which can pass back any object type. If the return value is null, you get a null object error from the cmdlet.

Note

The Write-Debug, Write-Host, and Write-Output cmdlets don't return values to your workflow. The return statement also doesn't return values to your workflow. However, you can use these cmdlets to write trace messages that appear in Application Insights. For more information, see Microsoft.PowerShell.Utility.

Syntax

Push-WorkflowOutput [-Output <Object>] [-Clobber]

Parameters

Parameter Type Description
Output Varies. The output that you want to return to the workflow. This output can have any type.
Clobber Varies. An optional switch parameter that you can use to override the previously pushed output.

Authenticate and authorize access with a managed identity using PowerShell

With a managed identity, your logic app resource and workflow can authenticate and authorize access to any Azure service and resource that supports Microsoft Entra authentication without including credentials in your code.

From inside the Execute PowerShell Code action, you can authenticate and authorize access with a managed identity so that you can perform actions on other Azure resources where you enabled access. For example, you can restart a virtual machine or get the run details of another logic app workflow.

To use the managed identity from inside the Execute PowerShell Code action, you must follow these steps:

  1. Follow these steps to set up the managed identity on your logic app and grant the managed identity access on the target Azure resource.

    On the target Azure resource, review the following considerations:

    • On the Role tab, a Contributor role is usually sufficient.

    • On the Add role assignment page, on the Members tab, for the Assign access to property, make sure that you select Managed identity.

    • After you select Select members, on the Select managed identities pane, select the managed identity that you want to use.

  2. In your Execute PowerShell Code action, include the following code as the first statement:

    Connect-AzAccount -Identity

  3. Now, you can work with the Azure resource using cmdlets and modules.

View the script file

  1. In the Azure portal, open your Standard logic app resource that has the workflow you want.

  2. On the logic app resource menu, under Development Tools, select Advanced Tools.

  3. On the Advanced Tools page, select Go, which opens the KuduPlus console.

  4. Open the Debug console menu, and select CMD.

  5. Go to your logic app's root location: site/wwwroot

  6. Go to your workflow's folder, which contains the .ps1 file, along this path: site/wwwroot/{workflow-name}

  7. Next to the file name, select Edit to open and view the file.

View logs in Application Insights

  1. In the Azure portal, on the logic app resource menu, under Settings, select Application Insights, and then select your logic app.

  2. On the Application Insights menu, under Monitoring, select Logs.

  3. Create a query to find any traces or errors from your workflow execution, for example:

    union traces, errors
| project TIMESTAMP, message

Modules

PowerShell modules are self-contained, reusable units that include various components, for example:

  • Cmdlets: Individual commands that perform specific tasks.
  • Providers: Allow access to data stores, such as the registry or file system, as if they were drives.
  • Functions: Reusable code blocks that perform specific actions.
  • Variables: Store data for use within the module.
  • Other types of resources.

A module organizes PowerShell code, making it easier to distribute. For example, you can create your own modules to package and make related functionality more manageable and shareable. The Execute PowerShell Code action lets you import both public and private PowerShell modules.

Public modules

To find publicly available modules, visit the PowerShell gallery. A Standard logic app resource can support up to 10 public modules. To use any public module, you must enable this capability by following these steps:

  1. In the Azure portal, on your logic app resource menus, under Development Tools, select Advanced Tools.

  2. On the Advanced Tools page, select Go.

  3. On the Kudu Plus toolbar, from the Debug console menu, select CMD.

  4. Browse to your logic app's root level at C:\home\site\wwwroot by using the directory structure or the command line.

  5. Open the workflow's host.json file, and set the managed dependency property to true, which is already set by default.

    "managedDependency": {
    "enabled": true
}

  6. Open the file named requirements.psd1. Include the name and version for the module that you want by using the following syntax: MajorNumber.* or the exact module version, for example:

    @{
    Az = '1.*'
    SqlServer = '21.1.18147'
}

Considerations for public modules

If you use dependency management, the following considerations apply:

  • To download modules, public modules require access to the PowerShell Gallery.

  • Managed dependencies currently don't support modules that require you to accept a license, either by accepting the license interactively or by providing the -AcceptLicense option when you run Install-Module.

Private modules

You can generate your own private PowerShell modules. To create your first PowerShell module, see Write a PowerShell Script Module.

  1. In the Azure portal, on your logic app resource menu, under Development Tools, selects Advanced Tools.

  2. On the Advanced Tools page, select Go.

  3. On the Kudu Plus toolbar, from the Debug console menu, select CMD.

  4. Browse to your logic app's root level at C:\home\site\wwwroot by using the directory structure or the command line.

  5. Create a folder named Modules.

  6. In the Modules folder, create a subfolder with the same name as your private module.

  7. In your private module folder, add your private PowerShell module file with the psm1 file name extension. You can also include an optional PowerShell manifest file with the psd1 file name extension.

When you're done, your complete logic app file structure appears similar to the following example:

MyLogicApp
-- execute_powershell_script.ps1
-- mytestworkflow.json
Modules
-- MyPrivateModule
--- MyPrivateModule.psd1
--- MyPrivateModule.psm1
-- MyPrivateModule2
--- MyPrivateModule2.psd1
--- MyPrivateModule2.psm1
requirements.psd1
host.json

Compilation errors

In this release, the web-based editor includes limited IntelliSense support, which is still under improvement. Any compilation errors are detected when you save your workflow, and the Azure Logic Apps runtime compiles your script. These errors appear in your logic app's error logs through Application Insights.

Runtime errors

A workflow action doesn't return any output.

Make sure that you use the Push-WorkflowOutput cmdlet.

Execute PowerShell Code action fails: "The term '{some-text}' is not recognized..."

If you incorrectly reference a public module in the requirements.psd1 file or when your private module doesn't exist in the following path: C:\home\site\wwwroot\Modules{module-name}, you get the following error:

The term '{some-text}' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name or if a path was included, verify the path is correct and try again.

Note

By default, the Az* modules appear in the requirements.psd1 file, but they're commented out at file creation. When you reference a cmdlet from the module, make sure to uncomment the module.

Execute PowerShell Code action fails: "Cannot bind argument to parameter 'Output' because it is null."

This error happens when you try to push a null object to the workflow. Confirm whether the object that you're sending with Push-WorkflowOutput isn't null.

Related content