Cisco UCS Activities
The Cisco UCS Integration Pack activities described in this chapter are located in the Activity pane of the Runbook Designer.
Note All parameters in square brackets [ ] are optional parameters.
This chapter includes the following sections:
•Connect-Ucs
•Disconnect-Ucs
•Get-UcsManagedObject
•Set-UcsManagedObject
•Add-UcsManagedObject
•Remove-UcsManagedObject
•Run-PowerTool
•Copy-UcsServiceProfile
•Add-UcsServiceProfileFromTemplate
•Get-UcsTechSupport
•Backup-Ucs
•Import-UcsBackup
•Get-UcsChild
•Confirm-UcsFault
Connect-Ucs
Definition
This activity establishes a new connection with the Cisco UCS domains. This activity is required in a runbook if you want to perform an operation on one or more Cisco UCS domains.
Parameter Set
HostName <String>, Username <String>, Password <String>, [NoSsl <Boolean>], [Port <UInt16>]
Parameters
Table 4-1 provides details of the parameters available for this activity.
Table 4-1 Parameter Definitions for Connect-Ucs
|
|
|
Hostname |
Host name/IP Address of Cisco UCS Manager |
ucs-manager-01 209.165.201.3 |
Username |
Valid login ID for Cisco UCS Manager |
admin |
Password |
Password for the username |
passw0rd |
NoSsl |
Use if you want to connect to Cisco UCS Manager with a non-secure (HTTP) connection |
Default value: False Press the ellipsis (...) button to view the acceptable values. |
Port |
Port number for connections to Cisco UCS Manager |
445 for HTTPS connections 88 for HTTP connections |
Published Data
<UcsHandle>
After successful execution, this activity publishes the UcsHandle object and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Disconnect-Ucs
Definition
This activity disconnects from one or more Cisco UCS domains. This activity disconnects all connections to Cisco UCS (UcsHandle connections created by Connect-Ucs) in a runbook.
You must specify the name of the Cisco UCS domain if you want to only disconnect from one domain. If you do not specify the name of the Cisco UCS domain from which you want to disconnect, all UcsHandles are disconnected.
Parameter Set
[Ucs<String>]
Parameters
Table 4-2 provides details of the parameters available for this activity.
Table 4-2 Parameter Definitions for Disconnect-Ucs
|
|
|
Ucs |
Comma separated names of Cisco UCS domains from which you want to disconnect. If you leave this value empty, this activity disconnects all handles created using Connect-Ucs in a runbook. |
ucs-manager-01 You can find the name of the Cisco UCS domain in the published output of the Connect-Ucs activity. |
Published Data
This activity does not publish output.
Get-UcsManagedObject
Definition
This activity is used to get one or more managed objects from a Cisco UCS domain. The output of this activity can be fed to other activities, such as Set-UcsManagedObject or Add-UcsManagedObject, to perform operations on that managed object. This activity supports filters that you can use to refine your search.
Parameter Set
Input <UcsHandle>, Dn <String>, [Hierarchy <Boolean>]
Input < UcsHandle >, ClassId <String>, [Filter <String>]
Input < UcsHandle >, XmlTag <String>, [Filter <String>]
Input <ManagedObject>, ClassId <String>, [Filter <String>]
Input <ManagedObject>, XmlTag <String>, [Filter <String>]
Parameters
Table 4-3 provides details of the parameters available for this activity.
Table 4-3 Parameter Definitions for Get-UcsManagedObject
|
|
|
Input |
Managed Object (Parent) or UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle or Managed Object. A value of type UcsHandle gets the managed object according to the Dn, ClassId, or XmlTag parameters. A value of type Managed Object is considered to be the parent object. This gets the managed object under that subscribed parent object, according to the parameters ClassId or XmlTag. |
{UcsScriptOutput from Connect-Ucs} {UcsScriptOutput from Get-UcsManagedObject} For example, you can subscribe from a Get-UcsManagedObject activity, which publishes a list of organizations, and also specify a value of lsServer for the ClassId parameter. With those values, this activity gets all service profiles under the subscribed organization list. |
Dn |
Distinguished name of the managed object. |
org-root/org-subOrg/ls-finSrvcProf sys/chassis-1 |
Hierarchy |
Includes children of the managed object as well as the object itself. |
Default value: False True |
ClassId |
Class ID of the managed object |
lsServer LsServer ComputeBlade |
Filter |
Filter string that you want to use to refine the search. Note Use a PowerTool compatible formatted filter and PowerTool compatible formatted syntaxes and wild cards in the filter strings. |
(type -clike *-template) (name -ilike finSrvcProf) |
XmlTag |
Class ID (case sensitive) of the managed object |
lsServer computeBlade |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Set-UcsManagedObject
Definition
This activity is used to modify and configure managed objects. The property map can include values that modify more than one property of the managed object. You can use those modified.values to configure the managed object.
Parameter Set
Input <ManagedObject>, PropertyMap <KeyValuePair>
Input list<ManagedObject>, PropertyMap <KeyValuePair>
Input <UcsHandle>, ClassId <String>, PropertyMap <KeyValuePair>
Input <UcsHandle>, XmlTag <String>, PropertyMap <KeyValuePair>
Parameters
Table 4-4 provides details of the parameters available for this activity.
Table 4-4 Parameter Definitions of Set-UcsManagedObject
|
|
|
Input |
Managed Object(s) or UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle or Managed Object. If you use a managed object or list of managed objects, such as a list of organizations, the property map includes the modifications that you wants to perform on the managed object or all managed objects in the list. If you use an input of type UcsHandle, the property map includes the key-value (modifications) for that UcsHandle. |
{UcsScriptOutput from Connect-Ucs} {UcsScriptOutput from Get-UcsManagedObject} |
PropertyMap |
PropertyMap contains one or more key-value pairs separated by semi-colons. For example, a property map could be: propertyName1="propertyValue1";PropertyName2="propertyValue2"... Note If the input is of type UcsHandle, the property map must include the Dn for that UcsHandle. Property names are case insensitive. However, these names must match the properties of the managed object. To find the names for a managed object's properties, see the XML schema or the output of the get cmdlet in PowerTool for that managed object. |
Dn="sys/chassis-1";Descr="modify" |
ClassId |
Class ID of the managed object |
lsServer equipmentChassis |
XmlTag |
Class ID (case sensitive) of the managed object |
lsServer orgOrg |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Add-UcsManagedObject
Definition
This activity is used to add one or more managed objects. To create a managed object, you must provide the classId (type of managed object) and a property map that sets the values of the properties of that managed object.
Parameter Set
Input <UcsHandle>, ClassId <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Input <UcsHandle>, XmlTag <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Input <ManagedObject>, ClassId <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Input <ManagedObject>, XmlTag <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Input list<ManagedObject>, ClassId <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Input list<ManagedObject>, XmlTag <String>, PropertyMap <KeyValuePair>, [ModifyPresent <Boolean>]
Parameters
Table 4-5 provides details of the parameters available for this activity.
Table 4-5 Parameter Definitions of Add-UcsManagedObject
|
|
|
Input |
Managed Object(s) or UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle or Managed Object. If you use a managed object or list of managed objects (parent), a new managed object of the specified classId/XmlTag is created under the subscribed managed object(s). If you use an input of type UcsHandle, a new managed object with the specified classId/XmlTag is created using the subscribed UcsHandle. |
{UcsScriptOutput from Connect-Ucs} {UcsScriptOutput from Get-UcsManagedObject} For example, if you use a list of organizations as a parent managed object, you can create service profiles under that subscribed list of organizations. |
ClassId |
Class ID of the managed object |
lsServer orgOrg |
PropertyMap |
PropertyMap contains one or more key-value pairs separated by semi-colons. These keys and values denote the properties and their values for the managed object that you want to create. For example, a property map could be: propertyName1="propertyValue1";PropertyName2="propertyValue2"... Note If the input is of type UcsHandle, the property map must include the Dn for that UcsHandle. |
Dn="org-root/org-subOrg";Descr="modify" |
ModifyPresent |
If the managed object already exists and this parameter is set to True, the activity modifies the existing managed object. |
True False Default Value: False |
XmlTag |
Class ID (case sensitive) of the managed object |
lsServer orgOrg |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Remove-UcsManagedObject
Definition
This activity is used to remove one or more managed objects. You can identify the managed object to be removed by providing the managed object or its Dn and classId.
Parameter Set
Input <ManagedObject>
Input list<ManagedObject>
Input <UcsHandle>, ClassId <String>, Dn <String>
Input <UcsHandle>, XmlTag <String>, Dn <String>
Parameters
Table 4-6 provides details of the parameters available for this activity.
Table 4-6 Parameter Definitions of Remove-UcsManagedObject
|
|
|
Input |
Managed Object(s) or UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle or Managed Object. If you use a managed object or list of managed objects, this activity removes those managed object(s). If you use an input of type UcsHandle, the specified Dn and classId determines which managed object is removed. |
{UcsScriptOutput from Connect-Ucs} {UcsScriptOutput from Get-UcsManagedObject} For example, if you use a list of organizations as a parent managed object, you can create service profiles under that subscribed list of organizations. |
ClassId |
Class ID of the managed object |
orgOrg fabricVlan |
Dn |
Distinguished name of the managed object. |
org-root/org-Finance sys/chassis-3 |
XmlTag |
Class ID (case sensitive) of the managed object |
orgOrg fabricVlan |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Run-PowerTool
Definition
This activity is used to run a PowerTool script. You can subscribe a UcsHandle from the Connect-Ucs activity and use that handle in the PowerTool script. You can also connect or disconnect the UcsHandle in the script itself. The output of this activity can be passed to another activity if you want to perform additional operations.
Parameter Set
Input<object>, Script<String>
Parameters
Table 4-7 provides details of the parameters available for this activity.
Table 4-7 Parameter Definitions of Run-PowerTool
|
|
|
Input |
Managed Object(s) or UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle or Managed Object. You can access the subscribed object/handle in the Script parameter directly using special `$ucsInput' variable. For more information, see the "Run Custom PowerTool Script" example in the Sample Runbooks. This parameter is optional. If you do not want to subscribe from any activity, leave this parameter empty. For example, if you do not want to subscribe from the Connect-Ucs activity, but instead you want to create a UcsHandle inside the PowerTool script, leave this parameter empty. |
{UcsScriptOutput from Connect-Ucs} {UcsScriptOutput from Get-UcsManagedObject} |
Script |
PowerTool script to run. You can paste an existing PowerTool script in this parameter and execute that script. Note In the PowerTool script, `$ucsInput' contains the input object(s) from a subscribed activity. Add any output object(s) to be published in `$ucsOutput', such as $ucsOutput.Add($obj). |
orgOrg fabricVlan |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Copy-UcsServiceProfile
Definition
This activity is used to make a copy of an existing service profile or service profile template.
Parameter Set
Input <LsServer>, NewName <String>, [DestinationOrgDn <String>], [Type <String>]
Parameters
Table 4-8 provides details of the parameters available for this activity.
Table 4-8 Parameter Definitions of Copy-UcsServiceProfile
|
|
|
Input |
Service Profile or Service Profile Template Managed object of type lsServer. You can subscribe from an activity which publishes an output of type lsServer managed object. |
{UcsScriptOutput from Get-UcsManagedObject} |
NewName |
Name of the service profile copy (new service profile name) |
orgOrg fabricVlan |
DestinationOrgDn |
Distinguished name of the organization where the service profile copy is to be created. Note If a DestinationOrgDn is not provided, the service profile copy is created under the root organization. |
org-root\org-Finance |
Type |
Type of service profile (copy). To choose a type, click on the ellipsis (...) button in the text box. You can choose one of the following types: •instance—The new copy will be a service profile. •initial-template—The new copy will be a service profile template of type initial. •updating-template—The new copy will be a service profile template of type updating. If you do not include a value for the type parameter, the type of service profile that is created depends on the Input parameter. If you subscribe a service profile template, the type will be initial-template. If you subscribe a service profile, the type will be instance. |
|
Published Data
<ManagedObject> or list<ManagedObject> (of type lsServer)
After successful execution, this activity publishes the managed object or the list of managed objects of type lsServer, and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Add-UcsServiceProfileFromTemplate
Definition
This activity is used to create one or more service profiles from a service profile template. To name the service profiles, you can either provide comma-separated names or "name prefix, count" values.
Parameter Set
InputManagedObject< ManagedObject >, NewName <String>, [DestinationOrgDn<String>]
InputManagedObject< ManagedObject >, Prefix <String>, Count <UInt32>, [DestinationOrgDn <String>]
Parameters
Table 4-9 provides details of the parameters available for this activity.
Table 4-9 Parameter Definitions of Add-UcsServiceProfileFromTemplate
Field |
|
|
InputManaged Object |
Managed Object(s) of type service profile template. Managed object of type lsServer. You can subscribe from an activity which publishes an output of type lsServer (service profile template) managed objects. You can use filters to get one or more managed objects of type service profile templates. For more information, see the "Add Service Profile From Template" runbook in the Sample Runbooks. |
{UcsScriptOutput from Get-UcsManagedObject} |
NewName |
Comma-separated names of the new service profiles that you want to create from the service profile template. |
financeServiceProfile, eduServiceProfile |
Prefix |
Prefix for the service profile names. |
finSP |
Count |
Number of service profiles that you want to create from the service profile template. |
5 |
DestinationOrgDn |
Distinguished name of the organization where the service profile copy is to be created. Note If a DestinationOrgDn is not provided, the service profile copy is created under the root organization. |
org-root/org-fin org-root/org-fin/org-account |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects (service profile) and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Get-UcsTechSupport
Definition
This activity is used to create and download a tech support file for a Cisco UCS domain. If desired, you can delete the tech support file from Cisco UCS Manager after you downloading the file. You can also choose various options for downloading the tech support file.
Parameter Set
Input<UcsHandle>, PathPattern<String>, UcsManager<Boolean>, [RemoveFromUcs<Boolean>], [TimeOutSec<UInt32>]
Input<UcsHandle>, PathPattern<String>, ChassisId<UInt16>, [CimcId<String>], [IomId<String>], [RemoveFromUcs<Boolean>], [TimeOutSec<UInt32>]
Input<UcsHandle>, PathPattern<String>, FexId<UInt16>, [RemoveFromUcs<Boolean>], [TimeOutSec<UInt32>]
Input<UcsHandle>, PathPattern<String>, RackServerId<UInt16>, [RackAdapterId<UInt16>], [RemoveFromUcs<Boolean>], [TimeOutSec<UInt32>]
Parameters
Table 4-10 provides details of the parameters available for this activity.
Table 4-10 Parameter Definitions of Get-UcsTechSupport
Field |
|
|
Input |
UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle. |
{UcsScriptOutput from Connect-Ucs} |
PathPattern |
Full name (including location) of the file you want to create. Note The path may contain DateTime format specifiers, as well as a custom format specifier `ucs' which relates to the Cisco UCS name. For example: C:\Folder\${ucs}-${yyyy}${MM}${dd}-${HH}${mm}.tar |
C:/subfold/techSupp.tar |
RemoveFromUcs |
If this parameter is set to True, the tech support file is deleted from Cisco UCS Manager after it is downloaded. Use the ellipsis (...) to choose a value for this parameter. |
True False Default Value: False |
UcsManager |
Creates a tech support file for the entire Cisco UCS domain. Use the ellipsis (...) to choose a value for this parameter. |
|
TimeOutSec |
Timeout duration in seconds. |
Default Value: 600 seconds |
ChassisId |
ID of the chassis for which you want to create a tech support file. |
|
CimcId |
ID of the CIMC for which you want to create a tech support file. |
|
IomId |
ID of the I/O module for which you want to create a tech support file. |
|
FexId |
ID of the FEX for which you want to create a tech support file. |
|
RackServerId |
ID of the rack-mount server for which you want to create a tech support file. |
|
RackAdapterId |
ID of the adapter in the rack-mount server for which you want to create a tech support file. |
|
Published Data
This activity does not publish output.
Backup-Ucs
Definition
This activity is used to create and download a backup file from a Cisco UCS domain. The backup file can be a snapshot of all or part of the system configuration, and can be exported to a file.
Parameter Set
Input<UcsHandle>, Type<String>, PathPattern<String>, [PreservePooledValues<Boolean>], [TimeOutSec<UInt32>]
Parameters
Table 4-11 provides details of the parameters available for this activity.
Table 4-11 Parameter Definitions of Backup-Ucs
Field |
|
|
Input |
UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle. |
{UcsScriptOutput from Connect-Ucs} |
Type |
The type of backup that you want to create. This can be one of the following types: •full-state—A binary file that includes a snapshot of the entire system. •config-all—An XML file that includes all system and logical configuration settings. •config-system—An XML file that includes all system configuration settings such as usernames, roles and locales. •config-logical—An XML file that includes all logical configuration settings such as service profiles, VLANs, VSANs, pools, and policies. Use the ellipsis (...) to choose a value for this parameter. |
full-state |
PathPattern |
Full name (including location) of the backup file you want to create. Note The path may contain DateTime format specifiers, as well as a custom format specifier `ucs' which relates to the Cisco UCS name. For example: C:\Folder\${ucs}-${yyyy}${MM}${dd}-${HH}${mm}.tar |
C:/subfold/full-stateBackup.xml |
PreservePooled Values |
If this parameter is set to True, the backup preserves the values of vHBAs, WWPNs, vNICs, MAC addresses, WWNNs, and UUIDs that are derived from pools. Use the ellipsis (...) to choose a value for this parameter. |
True False Default: False for backups of type full-state and config-system |
TimeOutSec |
Timeout duration in seconds. |
Default Value: 600 seconds |
Published Data
This activity does not publish output.
Import-UcsBackup
Definition
This activity is used to import a Cisco UCS backup file.
Note You cannot import a full-state configuration file.
Parameter Set
Input<UcsHandle>, LiteralPath<String>, [Merge<Boolean>]
Input<UcsHandle>, Path<String>, [Merge<Boolean>]
Parameters
Table 4-12 provides details of the parameters available for this activity.
Table 4-12 Parameter Definitions of Import-UcsBackup
Field |
|
|
Input |
UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle. |
{UcsScriptOutput from Connect-Ucs} |
LiteralPath |
Exact path to the backup file that you want to import. |
C:/subfold/All-ConfigBackup.xml |
Merge |
If this parameter is set to True, the activity merges the contents of the backup file into the existing configuration state. |
True False Default: False |
Path |
Path to the backup file that you want to import, including wildcard characters. |
C:\work\config?.xml |
Published Data
This activity does not publish output.
Get-UcsChild
Definition
This activity is used to get the child objects of a managed object. If you subscribe a managed object in the InputManagedObject parameter, you get all the immediate children of that managed object.
Parameter Set
InputManagedObject< ManagedObject >, [ClassId<String>], [Hierarchy<Boolean>]
Parameters
Table 4-13 provides details of the parameters available for this activity.
Table 4-13 Parameter Definitions of Get-UcsChild
Field |
|
|
Input |
Managed Object You can use any value from a previous activity whose output (published data) is of type Managed Object. |
{UcsScriptOutput from Get-UcsManagedObject} |
classId |
The classId of the child objects. |
lsServer |
Hierarchy |
If this parameter is set to True, the activity includes the child objects at all levels of the hierarchy. Use the ellipsis (...) to choose a value for this parameter. |
True False Default: False |
Published Data
<ManagedObject> or list<ManagedObject>
After successful execution, this activity publishes the managed object or the list of managed objects (service profile) and makes it available for other activities to use through UcsScriptOutput. If an error occurs, an error message is populated in the default Error summary text field in the SCO.
Confirm-UcsFault
Definition
This activity is used to acknowledge faults.
Parameter Set
InputUcsHandle< UcsHandle >, Id<ulong>
Parameters
Table 4-14 provides details of the parameters available for this activity.
Table 4-14 Parameter Definitions of Confirm-UcsFault
Field |
|
|
InputUcsHandle |
UcsHandle You can use any value from a previous activity whose output (published data) is of type UcsHandle. |
{UcsScriptOutput from Connect-Ucs} |
Id |
The ID of the fault that you want to acknowledge. |
3171250 |
Published Data
This activity does not publish output.