AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the Amazon Omics StartRun API operation.

Syntax

Start-OMICSRun
-RoleArn <String>
-CacheBehavior <CacheBehavior>
-CacheId <String>
-ConfigurationName <String>
-EngineSetting <PSObject>
-LogLevel <RunLogLevel>
-Name <String>
-NetworkingMode <NetworkingMode>
-OutputUri <String>
-Parameter <PSObject>
-Priority <Int32>
-RequestId <String>
-RetentionMode <RunRetentionMode>
-RunGroupId <String>
-RunId <String>
-ScratchStorageMode <ScratchStorageMode>
-StorageCapacity <Int32>
-StorageType <StorageType>
-Tag <Hashtable>
-WorkflowId <String>
-WorkflowOwnerId <String>
-WorkflowType <WorkflowType>
-WorkflowVersionName <String>
-Select <String>
-Force <SwitchParameter>
-ClientConfig <AmazonOmicsConfig>

Description

Starts a new run and returns details about the run, or duplicates an existing run. A run is a single invocation of a workflow. If you provide request IDs, Amazon Web Services HealthOmics identifies duplicate requests and starts the run only once. Monitor the progress of the run by calling the GetRun API operation. To start a new run, the following inputs are required:
  • A service role ARN (roleArn).
  • The run's workflow ID (workflowId, not the uuid or runId).
  • An Amazon S3 location (outputUri) where the run outputs will be saved.
  • All required workflow parameters (parameter), which can include optional parameters from the parameter template. The run cannot include any parameters that are not defined in the parameter template. To see all possible parameters, use the GetRun API operation.
  • For runs with a STATIC (default) storage type, specify the required storage capacity (in gibibytes). A storage capacity value is not required for runs that use DYNAMIC storage.
StartRun can also duplicate an existing run using the run's default values. You can modify these default values and/or add other optional inputs. To duplicate a run, the following inputs are required:
  • A service role ARN (roleArn).
  • The ID of the run to duplicate (runId).
  • An Amazon S3 location where the run outputs will be saved (outputUri).
To learn more about the optional parameters for StartRun, see Starting a run in the Amazon Web Services HealthOmics User Guide. Use the retentionMode input to control how long the metadata for each run is stored in CloudWatch. There are two retention modes:
  • Specify REMOVE to automatically remove the oldest runs when you reach the maximum service retention limit for runs. It is recommended that you use the REMOVE mode to initiate major run requests so that your runs do not fail when you reach the limit.
  • The retentionMode is set to the RETAIN mode by default, which allows you to manually remove runs after reaching the maximum service retention limit. Under this setting, you cannot create additional runs until you remove the excess runs.
To learn more about the retention modes, see Run retention mode in the Amazon Web Services HealthOmics User Guide. You can use Amazon Q CLI to analyze run logs and make performance optimization recommendations. To get started, see the Amazon Web Services HealthOmics MCP server on GitHub.

Parameters

-CacheBehavior <CacheBehavior>
The cache behavior for the run. You specify this value if you want to override the default behavior for the cache. You had set the default value when you created the cache. For more information, see Run cache behavior in the Amazon Web Services HealthOmics User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CacheId <String>
Identifier of the cache associated with this run. If you don't specify a cache ID, no task outputs are cached for this run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ClientConfig <AmazonOmicsConfig>
Amazon.PowerShell.Cmdlets.OMICS.AmazonOmicsClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ConfigurationName <String>
Optional configuration name to use for the workflow run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-EngineSetting <PSObject>
Engine-specific settings for the workflow run. Use this field to specify configuration options that are specific to the workflow engine (for example, Nextflow profiles).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesEngineSettings
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-LogLevel <RunLogLevel>
A log level for the run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Name <String>
A name for the run. This is recommended to view and organize runs in the Amazon Web Services HealthOmics console and CloudWatch logs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkingMode <NetworkingMode>
Optional configuration for run networking behavior. If not specified, this will default to RESTRICTED.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-OutputUri <String>
An output S3 URI for the run. The S3 bucket must be in the same region as the workflow. The role ARN must have permission to write to this S3 bucket.
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
-Parameter <PSObject>
Parameters for the run. The run needs all required parameters and can include optional parameters. The run cannot include any parameters that are not defined in the parameter template. To retrieve parameters from the run, use the GetRun API operation.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesParameters
-Priority <Int32>
Use the run priority (highest: 1) to establish the order of runs in a run group when you start a run. If multiple runs share the same priority, the run that was initiated first will have the higher priority. Runs that do not belong to a run group can be assigned a priority. The priorities of these runs are ranked among other runs that are not in a run group. For more information, see Run priority in the Amazon Web Services HealthOmics User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RequestId <String>
An idempotency token used to dedupe retry requests so that duplicate runs are not created.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RetentionMode <RunRetentionMode>
The retention mode for the run. The default value is RETAIN. Amazon Web Services HealthOmics stores a fixed number of runs that are available to the console and API. In the default mode (RETAIN), you need to remove runs manually when the number of run exceeds the maximum. If you set the retention mode to REMOVE, Amazon Web Services HealthOmics automatically removes runs (that have mode set to REMOVE) when the number of run exceeds the maximum. All run logs are available in CloudWatch logs, if you need information about a run that is no longer available to the API.For more information about retention mode, see Specifying run retention mode in the Amazon Web Services HealthOmics User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RoleArn <String>
A service role for the run. The roleArn requires access to Amazon Web Services HealthOmics, S3, Cloudwatch logs, and EC2. An example roleArn is arn:aws:iam::123456789012:role/omics-service-role-serviceRole-W8O1XMPL7QZ. In this example, the AWS account ID is 123456789012 and the role name is omics-service-role-serviceRole-W8O1XMPL7QZ.
Required?True
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-RunGroupId <String>
The run's group ID. Use a run group to cap the compute resources (and number of concurrent runs) for the runs that you add to the run group.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RunId <String>
The ID of a run to duplicate.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ScratchStorageMode <ScratchStorageMode>
Optional configuration for enabling scratch ephemeral storage mounted at /tmp. If not specified, this will default to SHARED. This configuration is applicable only for CPU tasks. For tasks using GPUs, scratch storage is always LOCAL.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is '*'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.Omics.Model.StartRunResponse). Specifying the name of a property of type Amazon.Omics.Model.StartRunResponse will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StorageCapacity <Int32>
The STATIC storage capacity (in gibibytes, GiB) for this run. The default run storage capacity is 1200 GiB. If your requested storage capacity is unavailable, the system rounds up the value to the nearest 1200 GiB multiple. If the requested storage capacity is still unavailable, the system rounds up the value to the nearest 2400 GiB multiple. This field is not required if the storage type is DYNAMIC (the system ignores any value that you enter).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StorageType <StorageType>
The storage type for the run. If you set the storage type to DYNAMIC, Amazon Web Services HealthOmics dynamically scales the storage up or down, based on file system utilization. By default, the run uses STATIC storage type, which allocates a fixed amount of storage. For more information about DYNAMIC and STATIC storage, see Run storage types in the Amazon Web Services HealthOmics User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Tag <Hashtable>
Tags for the run. You can add up to 50 tags per run. For more information, see Adding a tag in the Amazon Web Services HealthOmics User Guide. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesTags
-WorkflowId <String>
The run's workflow ID. The workflowId is not the UUID.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-WorkflowOwnerId <String>
The 12-digit account ID of the workflow owner that is used for running a shared workflow. The workflow owner ID can be retrieved using the GetShare API operation. If you are the workflow owner, you do not need to include this ID.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-WorkflowType <WorkflowType>
The run's workflow type. The workflowType must be specified if you are running a READY2RUN workflow. If you are running a PRIVATE workflow (default), you do not need to include the workflow type.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-WorkflowVersionName <String>
The name of the workflow version. Use workflow versions to track and organize changes to the workflow. If your workflow has multiple versions, the run uses the default version unless you specify a version name. To learn more, see Workflow versioning in the Amazon Web Services HealthOmics User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.Omics.Model.StartRunResponse
This cmdlet returns an Amazon.Omics.Model.StartRunResponse object containing multiple properties.
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z