Machine Extensibility vRealize Automation 6.
Machine Extensibility You can find the most up-to-date technical documentation on the VMware website at: https://docs.vmware.com/ If you have comments about this documentation, submit your feedback to docfeedback@vmware.com VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com Copyright © 2008–2014 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc.
Contents Machine Extensibility 6 Updated Information for Machine Extensibility 7 1 Machine Extensibility Overview 8 Machine Life Cycle Extensibility 8 Choosing a Lifecycle Extensibility Scenario 9 2 Extending Machine Lifecycles By Using vRealize Orchestrator 11 Extending Machine Lifecycles by Using vRealize Orchestrator Checklist Installing the vRealize Automation Plug-In 11 12 vCenter Orchestrator Integration Prerequisites 12 vRealize Automation Plug-In Functional Prerequisites 12 Install th
Machine Extensibility Remove Associations between Skills and DEM Workers Remove Associations between Skills and Workflows Remove a Skill 41 41 42 5 CloudUtil Command Reference 43 DEM Commands 43 DEM-Add-Skills 43 DEM-List 44 DEM-Remove-Skills File Commands 44 45 File-Export 45 File-Import 45 File-List 46 File-Remove-All 46 File-Remove-Rev File-Rollback 47 47 File-Update 48 Operation Commands 48 Operation-Create 48 Operation-Delete 49 Operation-List Skill Commands 49 Skill-Instal
Machine Extensibility DeleteObject 58 InvokeRepositoryWorkflow LoadProperty 58 SaveChanges 58 SetLink 59 UpdateObject 59 DynamicOps.Cdk.Activities 59 ExecutePowerShellScript ExecuteSshScript 60 GetMachineName 61 GetMachineOwner 61 GetMachineProperties 62 GetScriptFromName 62 62 InvokeSshCommand LogMachineEvent LogMessage 64 RunProcess 64 SendEmail 59 61 GetMachineProperty InvokePowerShell 63 64 65 SetMachineProperty SetWorkflowResult VMware, Inc.
Machine Extensibility Machine Extensibility provides information about customizing IaaS workflows by using vRealize Orchestrator as well as vRealize Automation Designer and its associated command-line tools. It covers the following subjects: n Customizing IaaS machine state change workflows, including calling vRealize Orchestrator workflows from IaaS by using vRealize Orchestrator or vRealize Automation Designer. n Installing and configuring the vRealize Automation plug-in.
Updated Information for Machine Extensibility This Machine Extensibility is updated with each release of the product or when necessary. This table provides the update history of the Machine Extensibility . Revision Description EN-001637-01 n Revised location in Install vRealize Orchestrator Customization. n Added VcoEndpointName as an additional endpoint option in Call a vRealize Orchestrator Workflow.
Machine Extensibility Overview 1 Provisioning or decommissioning a new machine, especially for mission-critical systems, typically requires interacting with a number of different management systems, including DNS servers, load balancers, CMDBs, IP Address Management and other systems.
Machine Extensibility Figure 1‑3. Master workflow states for machine lease expiration Figure 1‑4. Master workflow states for disposing a machine Table 1‑1. Customizable State Change Workflows Master Workflow State Customizable Workflow Name Extensibility Examples BuildingMachine WFStubBuildingMachine Prepare for the machine to be created on the hypervisor.
Machine Extensibility Table 1‑2. Choosing a Lifecycle Extensibility Scenario Scenario Procedure Inject custom logic into predetermined stages of the IaaS machine lifecycle and apply that custom logic to specific blueprints. Extending Machine Lifecycles by Using vRealize Orchestrator Checklist Inject custom logic into predetermined stages of the IaaS machine lifecycle and apply that custom logic globally to all of your blueprints.
Extending Machine Lifecycles By Using vRealize Orchestrator 2 You can inject custom logic into predetermined stages of the IaaS machine lifecycle by creating custom vRealize Orchestrator workflows and then using vRealize Orchestrator to insert the custom workflows into the lifecycle of machines built from specific blueprints.
Machine Extensibility Table 2‑1. Extending Machine Lifecycles by Using vRealize Orchestrator Checklist (Continued) Task Details Create a vRealize Automation endpoint for your vRealize Orchestrator instance. Create a vRealize Orchestrator Endpoint Use the workflow template provided in the Extensibility subdirectory of the vRealize Automation plugin library to create a custom vRealize Orchestrator workflow to run during the machine lifecycle.
Machine Extensibility vRealize Automation You must have access to a vRealize Automation server. Version 6.2 of the plug-in works with vRealize Automation 6.2. For information about setting up vRealize Automation, see vRealize Automation Installation and Configuration. vRealize Orchestrator Server Version 6.2 of the plug-in works with vRealize Orchestrator 6.0.0. For information about setting up Orchestrator, see Installing and Configuring VMware vRealize Orchestrator.
Machine Extensibility Configuring the vRealize Automation Plug-in for Machine Extensibility You configure your vRealize Automation and IaaS hosts, install the customizations for machine extensibility, and create a vRealize Automation endpoint for your vRealize Orchestrator instance. Add a vRealize Automation Host You can run a workflow to a vRealize Automation host and configure the host connection parameters. Procedure 1 From the drop-down menu in the Orchestrator client, select Run or Design.
Machine Extensibility What to do next Add a vRealize Automation Infrastructure Administration host. Add an IaaS Host You can run a workflow to add the IaaS host of a vRealize Automation host and configure the connection parameters. Procedure 1 From the drop-down menu in the Orchestrator client, select Run or Design. 2 Click the Workflows view. 3 Select Library > vCloud Automation Center > Configuration. 4 Right-click Add the IaaS host of a vCAC host and select Start workflow.
Machine Extensibility Install vRealize Orchestrator Customization You can run a workflow to install the customized state change workflow stubs and Orchestrator menu operation workflows. Procedure 1 From the drop-down menu in the Orchestrator client, select Run or Design. 2 Click the Workflows view. 3 Select Library > vCloud Automation Center > Infrastructure Administration > Extensibility > Installation. 4 Right-click the Install vCO customization workflow and select Start workflow.
Machine Extensibility 4 Type a URL with the fully qualified name or IP address of the vRealize Orchestrator server and the vRealize Orchestrator port number. The format depends on the version of the vRealize Orchestrator server. vRealize Orchestrator version URL format 5.1 https://hostname:port 5.5 https://hostname:port/vco The transport protocol must be HTTPS. If no port is specified, the default port 8281 is used.
Machine Extensibility Assign a State Change Workflow to a Blueprint and Its Virtual Machines You configure custom vRealize Orchestrator workflows to run at specific stages in the master machine workflow by associating your custom workflow with a state change workflow stub and assigning the workflows to a blueprint. Prerequisites Use the workflow template provided in the Extensibility subdirectory of the vRealize Automation plugin library to create a custom workflow to run during the machine lifecycle.
Extending Machine Lifecycles By Using vRealize Automation Designer 3 You can inject custom logic into predetermined stages of the IaaS machine life cycle by using vRealize Automation Designer to directly edit the state change workflow stubs and, optionally, call out to custom vRealize Orchestrator workflows.
Machine Extensibility Installing and Configuring vRealize Automation Designer You can install vRealize Automation Designer on a Windows machine and configure it to communicate with a remote Model Manager instance. If you are using IaaS workflows to call vRealize Orchestrator workflows, you must also configure the vRealize Orchestrator instance in IaaS.
Machine Extensibility 3 Click vRealize Automation Designer. 4 When prompted, save the installer. What to do next Install vRealize Automation Designer. Install vRealize Automation Designer The vRealize Automation Designer installer is packaged as Windows installation wizard. Prerequisites Download the vRealize Automation Designer Installer. Procedure 1 Navigate to the directory where you downloaded the installer. 2 Right-click DesignCenter-Setup.exe and select Run as administrator.
Machine Extensibility You can associate a vRealize Orchestrator endpoint with a multi-machine blueprint to make sure that all of the vRealize Orchestrator workflows for machines provisioned from that blueprint are run using that endpoint. vRealize Automation by default includes an embedded vRealize Orchestrator instance. It is recommended that you use this as your vRealize Orchestrator endpoint for running vRealize Automation workflows in a test environment or creating a proof of concept .
Machine Extensibility 4 Type a URL with the fully qualified name or IP address of the vRealize Orchestrator server and the vRealize Orchestrator port number. The format depends on the version of the vRealize Orchestrator server. vRealize Orchestrator version URL format 5.1 https://hostname:port 5.5 https://hostname:port/vco The transport protocol must be HTTPS. If no port is specified, the default port 8281 is used.
Machine Extensibility Procedure 1 Select Infrastructure > Blueprints > Blueprints. 2 Create a new blueprint or edit an existing blueprint. If you are editing an existing blueprint, the vRealize Orchestrator endpoint you specify only applies to new machines provisioned from the updated blueprint. Existing machines provisioned from the blueprint continue to use the highest priority endpoint unless you manually add this property to the machine. 3 Click the Properties tab. a Click New Property.
Machine Extensibility The Toolbox pane on the left provides access to the vRealize Automation workflow activity library. You can drag activities from the toolbox onto the Designer pane to add them to a workflow. The Properties pane displays the configurable properties of the currently selected activity on the Designer pane. This interface is very similar to the workflow designer in Visual Studio.
Machine Extensibility The Imports tab displays imported namespaces from which you can select entity types to add to the workflow. The collapsible Information pane at the bottom of the console displays any errors in configuring activities and provides access to the XAML representation of the workflow. IaaS Workflow Types You can customize two types of workflows by using vRealize Automation Designer: state change workflows and menu operation workflows.
Machine Extensibility vRealize Automation Designer provides a customizable workflow for each of these states. Table 3‑2.
Machine Extensibility In addition to the workflow definition, a menu operation workflow depends on an operation configuration file, which defines the aspects of the custom menu option such as the display text, which roles have access to it, and the machine states for which the operation is available. Note A service architect can define custom actions for any catalog item by using the Advanced Service Designer. For more information, see Advanced Service Design.
Machine Extensibility 2 3 Select the workflow that you want to customize.
Machine Extensibility Synchronous Execution The InvokeVcoWorkflow activity calls a vRealize Orchestrator workflow and blocks further execution of its parent IaaS workflow until the vRealize Orchestrator workflow completes. The activity returns the output parameters for the vRealize Orchestrator workflow. In addition, the synchronous execution supports the following property: n WorkflowTimeout is a timeout value in seconds.
Machine Extensibility 2 Drag the InvokeVcoWorkflow or the InvokeVcoWorkflowAsync activity into the Designer pane. 3 Select the vCenter Orchestrator workflow to execute. a Under General, click the ellipsis next to Workflow. b In the Browse for vCO workflow dialog box, select a workflow. c Click OK. The Inputs and Outputs sections display the input and output parameters of the selected workflow. 4 In the Properties pane, specify one of the following target parameters.
Machine Extensibility Prerequisites Call a vRealize Orchestrator Workflow using the InvokeVcoWorkflowAsync activity. Procedure 1 In vRealize Automation Designer, open a workflow where you have used the InvokeVcoWorkflowAsync activity. 2 Navigate to the context where you want to check the status of the vRealize Orchestrator workflow. 3 Drag the GetVcoWorkflowExecutionStatus activity into the Designer pane.
Machine Extensibility 3 Drag the WaitForVcoWorkflowCompletion activity into the Designer pane. 4 In the Properties pane, specify the name of the variable representing the virtual machine ID in VirtualMachineId. The customizable workflows contain a variable by default named virtualMachineId that is set during initialization. 5 Create a variable of type DynamicOps.VcoModel.Common.VcoWorkflowExecutionToken. 6 Create a variable of type DynamicOps.VcoModel.Common.VcoWorkflowExecutionToken.
Machine Extensibility Table 3‑3. vRealize Orchestrator and IaaS Object Types (Continued) vRealize Orchestrator Type IaaS Type Date DateTime VC:VirtualMachine VirtualMachine Note If you are using vRealize Orchestrator 5.1, you must have installed the vRealize Automation integration package to enable the conversion of VC:VirtualMachine object types to VirtualMachine. All other vRealize Orchestrator types are converted to the IaaS type VcoSdkObject.
Machine Extensibility 6 Leave the Value text box blank. The workflow depends on the presence of the property, not on any particular value. 7 Click the Save icon ( 8 Click OK. ). The workflow is now enabled for new machines that are provisioned from this blueprint. Configuring a Menu Operation Workflow After you customize a menu operation workflow, additional configuration is required before it is available to users in the vRealize Automation console.
Machine Extensibility 2 Create the root element customOperations. The element must specify the XML namespace http://www.dynamicops.com/schemas/2009/OperationConfig/. 3 For each operation you want to define, add an operation element within customOperations.
Machine Extensibility 5 (Optional) Specify the machine states for which the operation is available. a Add the machineStates element. b For each state in which the operation should be available, add a state element. On Off The value may be any of the possible machine states.
Machine Extensibility 2 Run the CloudUtil.exe command with the following arguments. n n CloudUtil.exe Operation-Create -c Optionally, you can specify a Model Manager host and request a stack trace in case of error. CloudUtil.
Machine Extensibility Procedure 1 Select Infrastructure > Blueprints > Blueprints. 2 Point to the name of a blueprint and click Edit. 3 Click the Actions tab. 4 Select the checkbox that corresponds to the operation that you want to enable. 5 Click OK. The menu operation is now enabled for machines provisioned from this blueprint and available to all user roles specified in the operation configuration file.
Workflows and Distributed Execution Management 4 You can use skills to restrict execution of workflows to specific Distributed Execution Managers. A skill is similar to a tag that you can apply to both workflows and DEM Worker instances. If a workflow is not associated with any skills, any DEM Worker can execute it. If a workflow is associated with one or more skills, then only DEM Workers that are associated with all of the same skills can execute it.
Machine Extensibility 3 Select the name of the skill in the list on the left. 4 Associate the skill with one or more DEM Workers. 5 a Click the Add icon ( b In the Select DEMs dialog, select one or more DEM Worker instances. c Click OK. ) next to Distributed Execution Managers. Associate the skill with one or more Workflows. a Click the Add icon ( b In the Select Workflows dialog, select one or more workflows. c Click OK. ) next to Workflows.
Machine Extensibility 2 In the Manage Skills dialog, select the name of the skill in the list on the left. 3 Select the name of one or more workflows from the Workflows list and click the Remove icon ( 4 Click OK to close the Manage Skills dialog and save your changes to the Model Manager. ). Remove a Skill Removing a skill also removes its associations to any DEM Workers and workflows. Prerequisites Launch the vRealize Automation Designer console. Procedure 1 On the ribbon, click Manage Skills.
CloudUtil Command Reference 5 This section provides a reference to the commands in the CloudUtil command line interface. Note In the CloudUtil commands, the Model Manager is referred to as the repository and a Distributed Execution Manager (DEM) is referred to as an agent.
Machine Extensibility DEM-Add-Skills Arguments Argument Description -n | - -name Name of a registered Distributed Execution Manager. - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository. Default is specified in the CloudUtil config file in the repositoryAddress key under the section. -s | - -skills Comma-delimited list of skills to associate with this Distributed Execution Manager.
Machine Extensibility Argument Description -s | - -skills Comma-delimited list of skills to remove from this Distributed Execution Manager. -v | - -verbose (Optional) If an error occurs, outputs a stack trace instead of just the exception message. File Commands The File commands enable you to store and manage files (typically scripts) in the Model Manager. File-Export Exports a file from the Model Manager. Synopsis CloudUtil.
Machine Extensibility Argument Description -n | - -name Friendly name to assign to the file in the Model Manager. - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository. Default is specified in the CloudUtil config file in the repositoryAddress key under the section. -v | - -verbose (Optional) If an error occurs, outputs a stack trace instead of just the exception message. File-List Lists all files imported into the Model Manager.
Machine Extensibility File-Remove-Rev Removes a specific revision of a file from the Model Manager. Synopsis CloudUtil.exe File-Remove-Rev -n|--name -r|--revision [-i|--iteration ] [--repository ] [-v|--verbose] File-Export Arguments Argument Description -i | - -iteration (Optional) Version string of the file in the Model Manager. Default is 0.0. -n | - -name Friendly name of the file in the Model Manager.
Machine Extensibility File-Update Updates a previously imported file in the Model Manager with a new revision. Synopsis CloudUtil.exe File-Update -n|--name -f|--filename [-i|--iteration ] [-repository ] [-v|--verbose] File-Update Arguments Argument Description -f | - -filename Path to the updated file. -i | - -iteration (Optional) Version string of the file in the Model Manager. Default is 0.0.
Machine Extensibility Operation-Delete Deletes a custom operation from the Model Manager. Synopsis CloudUtil.exe Operation-Delete -n|--name [--force] [--repository ] [-v|--verbose] Operation-Delete Arguments Argument Description - -force (Optional) Force deletion of the operation. -n | - -name Name of the custom operation in the Model Manager. - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository.
Machine Extensibility Synopsis CloudUtil.exe Skill-Install -n|--name [--repository ] [-v|--verbose] Skill-Install Arguments Argument Description -n | - -name Name for the skill in the Model Manager. - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository. Default is specified in the CloudUtil config file in the repositoryAddress key under the section.
Machine Extensibility Skill-Uninstall Arguments Argument Description -n | - -name Name of the skill to uninstall from the Model Manager. - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository. Default is specified in the CloudUtil config file in the repositoryAddress key under the section. -v | - -verbose (Optional) If an error occurs, outputs a stack trace instead of just the exception message.
Machine Extensibility Table 5‑4. Workflow-List Arguments Argument Description - -repository (Optional) The root URI of the Model Manager, for example, http://hostname/repository. Default is specified in the CloudUtil config file in the repositoryAddress key under the section. -v | - -verbose (Optional) If an error occurs, outputs a stack trace instead of just the exception message. Workflow-Remove-Skills Removes association between skills and a workflow in the Model Manager.
Machine Extensibility Argument Description -r | - -revision Revision of the workflow to revert to. -v | - -verbose (Optional) If an error occurs, outputs a stack trace instead of just the exception message. Workflow-Update Update a customizable workflow with a new revision. CloudUtil.exe Workflow-Update -f|--filename -n|--name [-d|--description ] [--repository ] [-v|--verbose] Table 5‑5.
Machine Extensibility Table 5‑6. (Continued) Argument Description -f | - -filename Specify the name of the CSV data file containing a list of machine names, for example, filename.csv. File is saved in the current path by default. You can also specify the complete path to a preferred directory. -g | - -group (Optional) Specify business group name, for example, Engineering. -i | - -ignore (Optional) Ignore invalid arguments. -m | - -managed (Optional) Export managed virtual machines.
Machine Extensibility Machine-BulkRegisterImport Arguments Table 5‑7. Argument Description -b | - -batch (Optional) Batch size -d | - -delay (Optional) Specify processing delay time in this format: hh:mm:ss, for example, 02:20:10. -f | - -filename Specify the CSV data file name containing the list of machine names. For example, filename.csv. -h | --humanreadable (Optional) Input file contains the virtual machine names and not the GUIDs.
vRealize Automation Workflow Activity Reference 6 VMware provides a library of workflow activities with vRealize Automation Designer for use in customizing workflows. Five categories of Windows Workflow Foundation activities are also included in vRealize Automation Designer, including Control Flow, Flowchart, Primitives, Collection and Error Handling. This section provides a reference to the IaaS workflow activities included with vRealize Automation Designer in the DynamicOps.Repository.
Machine Extensibility AddObject Adds the specified object to the set of objects the DataServiceContext is tracking. Table 6‑2. AddObject Activity Input Parameters Argument Type Description DataServiceContext RepositoryServiceContext The DataServiceContext to which to add the object. Instance Object The object to be tracked by the DataServiceContext. AttachTo Notifies the DataServiceContext to start tracking the specified resource. Table 6‑3.
Machine Extensibility Table 6‑6. DeleteLink Activity Input Parameters Argument Type Description DataServiceContext RepositoryServiceContext The DataServiceContext from which to delete the link. Source Object The source object in the link to be marked for deletion. SourceProperty String The name of the navigation property on the source object that is used to access the target object. Target Object The target object involved in the link that is bound to the source object.
Machine Extensibility Table 6‑10. SaveChanges Activity Input Parameters Argument Type Description DataServiceContext RepositoryServiceContext The DataServiceContext that is tracking the changes to save. SetLink Notifies the DataServiceContext that a new link exists between the objects specified and that the link is represented by the property specified in the SourceProperty argument. Table 6‑11.
Machine Extensibility Table 6‑13. ExecutePowerShellScript Activity Input Parameters Argument Type Description ScriptName String Name in the Model Manager of the script to execute. ScriptVersion Object (Optional) Version in the Model Manager of the script to execute. Default is 0.0. MachineId Guid (Optional) If specified, the machine is loaded and all its properties are passed to the script. Arguments Dictionary Additional arguments to pass to the script.
Machine Extensibility Table 6‑16. ExecuteSshScript Activity Output Parameters Argument Type Description EnvironmentVariables Dictionary Script execution result if any. GetMachineName Gets a machine’s name. Table 6‑17. GetMachineName Activity Input Parameters Argument Type Description MachineId Guid The machine whose name to retrieve. Table 6‑18. GetMachineName Activity Output Parameters Argument Type Description MachineName String Name of the machine identifed by MachineId.
Machine Extensibility GetMachineProperty Gets the value of the specified property for a machine. Table 6‑23. GetMachineProperty Activity Input Parameters Argument Type Description MachineId Guid The machine from which to retrieve a property. PropertyName String Name of the property whose value to return. IsRequired bool If the property is required and is not found the activity throws an exception, otherwise returns null. Table 6‑24.
Machine Extensibility Table 6‑27. InvokePowerShell Activity Input Parameters (Continued) Argument Type Description Parameters Collection (Optional) Collection of name-value pairs passed as parameters to the PowerShell script. This option is only available in the Properties pane and not in the Designer pane. PowerShellVariables Collection (Optional) Variables copied into the PowerShell runtime. This option is only available in the Properties pane and not in the Designer pane.
Machine Extensibility Table 6‑30. InvokeSshCommand Activity Output Parameters Argument Type Description EnvironmentVariables Dictionary Output of command if any. Throws exception on error. LogMachineEvent Logs a machine event to the user log that is visible to the machine owner. Table 6‑31. LogMachineEvent Activity Input Parameters Argument Type Description MachineId Guid Machine generating the event to log. Message String Message to write to the user log.
Machine Extensibility Table 6‑33. RunProcess Activity Input Parameters (Continued) Argument Type Description Arguments String (Optional) The list of command-line arguments to pass to the command. WaitForExit bool (Optional) If true, the workflow waits for the process to complete before continuing with the workflow. Default is false. This option is only available in the Properties pane and not in the Designer pane. SendEmail Sends an email to the given set of addresses. Table 6‑34.
Machine Extensibility Table 6‑35. SetMachineProperty Activity Input Parameters Argument Type Description MachineId Guid Machine on which to create or update the custom property. PropertyName String Name of property to create or update. PropertyValue String Value with which to create or update the property. IsEncrypted bool (Optional) Indicates whether the value of the property is encrypted. IsHidden bool (Optional) Indicates whether the property is a hidden property.
