createActualParameter

Summary

Creates a new actual parameter for a step that calls a nested procedure. The parameter is passed to the nested procedure when the step runs. At runtime, the actual parameter name must match the name of a formal parameter in the nested procedure.

You can use actual parameters in three types of API calls:

Calling runProcedure to start a new job.
Setting up a schedule.
Creating or modifying a subprocedure step.

For example, when you call runProcedure using ectool, set the actual parameters to the procedure on the command line using the optional argument --actualParameter, followed by a list of name/value pairs. The following is an example of calling a procedure named MainBuild:

`ectool runProcedure "project A" --procedureName "MainBuild" --actualParameter Branch=main Type=Debug`▼

To make this call using the Perl API, define a list. Each element of the list is an anonymous hash reference that specifies one of the actual parameters. Now you can pass a reference to the list as the value of the actualParameter argument.

Here is the same example called via the Perl API:

# Run the procedure
            $xPath = $cmdr->runProcedure("project A",
                  {procedureName => "MainBuild",
                 actualParameter => [
         {actualParameterName => 'Branch',
                        value => 'main'},
          actualParameterName => 'Type',
                        value => 'Debug'},
      ]});▼

Specifying most arguments to the createStep API in Perl is fairly intuitive; like any other API, you specify key-value pairs in a hash argument for all optional parameters. However, specifying actual parameters is more involved because actual parameters are not arbitrary key-values characterizing the step. Instead, they are key-values characterizing actual parameters to the step. Refer to the following createStep request in XML:

<createStep>
   <projectName>MyProject</projectName>
   <procedureName>MyProcedure</procedureName>
   <stepName>Step1</stepName>
   <actualParameter>
      <actualParameterName>parm1</actualParameterName>
      <value>myval</value>
   </actualParameter>
   <actualParameter>
      <actualParameterName>parm2</actualParameterName>
      <value>val2</value>
   </actualParameter>
</createStep>▼

Each actual parameter key-value is under an <actualParameter> element. Code this in the optional arguments hash in the Perl API like this:

{ ..., => ..., actualParameter => [{actualParameterName => 'parm1',
                                      value => 'myval'},
                       {actualParameterName => 'parm2',
                                      value => 'val2'}],
                                        ... => ...}▼

The value of the actualParameter key in the optional arguments hash is a list of hashes, each representing one actual parameter. If the sub-procedure call takes only one actual parameter, the value of the actualParameter key can be specified as just the hash representing the one parameter:

actualParameter => {actualParameterName => 'parm1',
                    value => 'myval'}▼

projectName

Stringrequired

The name for the project that must be unique among all projects.

procedureName

Stringrequired

The name of the procedure.

stepName

Stringrequired

The name of the step.

actualParameterName

Stringrequired

The name of the parameter to create/modify/delete.

applicationName

Stringoptional

The name of the application, if the actual parameter is on an application process step.

archiveConnectorName

Stringoptional

The name of the archive connector.

catalogItemName

Stringoptional

The name of the catalog item.

catalogItemRunId

Stringoptional

The ID of the catalog item run, if the actual parameter is on a catalog item run.

catalogName

Stringoptional

The name of the catalog.

componentName

Stringoptional

The name of the component, if the actual parameter is on a component process step.

dashboardName

Stringoptional

The name of the dashboard.

flowName

Stringoptional

The name of the flow to which the flow state belongs to.

flowStateName

Stringoptional

The name of the flow state, if the formal parameter is on a flow state.

pipelineName

Stringoptional

The name of the pipeline.

processName

Stringoptional

The name of the process, if the actual parameter is on a process step.

processStepName

Stringoptional

The name of the process step, if the actual parameter is on a process step.

releaseName

Stringoptional

The name of the release, if the actual parameter is on a release.

scheduleName

Stringoptional

The name of the schedule.

stateDefinitionName

Stringoptional

The name of the state definition.

tierMapName

Stringoptional

The name of the tier map.

transitionDefinitionName

Stringoptional

The name of the state definition.

triggerName

Stringoptional

The name of the trigger.

value

Stringoptional

The value of the actual parameter, if creating or modifying.

widgetName

Stringoptional

The name of the widget.

workflowDefinitionName

Stringoptional

The name of the workflow definition.

Usage

Perl

$cmdr->createActualParameter(
  "test-projectName", # projectName
  "test-procedureName", # procedureName
  "test-stepName", # stepName
  "test-actualParameterName" # actualParameterName
  # optionals
);▼

ectool

ectool createActualParameter \
  "test-projectName" `# projectName` \
  "test-procedureName" `# procedureName` \
  "test-stepName" `# stepName` \
  "test-actualParameterName" `# actualParameterName` \
  # optionals▼

Examples

Perl

$cmdr->createActualParameter("Default", "Take Snapshot", "Retrieve",
  "Source directory", {value => "local"});▼

ectool

ectool createActualParameter "Default" "Take Snapshot" "Retrieve"
 "Source directory" --value "local"▼