This article describes the procedure by which you can use a Jenkins automation server to request services in vCommander as part of building, deploying and installing a project. The example provided submits a vCommander® request and sets the build number as a text based custom attribute, which is then used to locate and install the build on a deployed VM.




Requirements


Creating the Custom Attribute

In our example, we will use a custom attribute to record the build number being generated in Jenkins.

  1. Under the Configuration menu, click Custom Attributes.
  2. Click Add.
  3. Configure the attribute as follows:

    Name: Build
    Description: Jenkins build number
    Type: Text
    Applies To: Services (VMs, Virtual Services, etc.)
    Edit in Service Portal: Enabled



  4. Click Next.

  5. Choose Free Form to accept any characters for your build number or Specific Format to enforce a pattern you describe with regular expressions configuring the options for the latter.  

  6. Click Finish.


Creating the Service Form

 As a best practice, create a Service Form specifically for API interactions. In doing so, you avoid situations where information you collect on the global form for human users interferes with the API based automation. In our example, we're adding the custom attribute we created above, and the expiry date control.


  1. Under the Configuration menu, choose Service Request Configuration.
  2. Switch to the Form Designer tab.
  3. In the Form Library section, click Add.
  4. Configure the form as follows, then click OK:

    Form Name: API account form
    Form Type: New Request Service Form
    Choose Publish - Specific organizations, users and groups and specify the user account you'll use for the API calls.


  5. Delete all of the form contents except Expiry Date in the middle section.
  6. Under the Toolbox, click Custom Attribute and select Build from the form tool and click OK.


  7. Click Save.


Preparing the Service Catalog Entry

The example in this article is meant as a 1:1 solution. The script you'll import into Jenkins names a specific vCommander service to deploy. You can set this up however you please, but you must know the display name of the service. Below, the display name of the service is Builder.


Using the Jenkins Script to Request Services

You must install the Embotics vCommander PowerShell libraries on your Jenkins server before proceeding. Follow the instructions for doing this and creating an encrypted credentials file found in the vCommander REST API Getting Started Guide.

Next, you'll use the script attached to this article with Jenkins to request VMs. 

  1. Download the Jenkins Deploy script package to the vCommander application server.
  2. Edit the lines highlighted in the image below as follows:

    On line 8, enter the FQDN for your vCommander server between the single quotes.
    On line 9, enter the location of the local encrypted credentials file between the single quotes. Refer to instructions in the REST API Getting Started Guide. Use the credentials for which you created the form above.
    On line 11, enter the name of the service to request between the double quotes. To request more than one service, delimit the list with commas.
    On line 12, enter the number of days for the service to live between the single quotes. This sets the deployed VMs' expiry date using an offset of the number of days entered.

  3. Configure Jenkins to run this script to request the service upon which the new build will be installed.



Running this script as part of your automation picks up the build number and populates the custom attribute when the service is requested from vCommander. This allows you to specify a dynamic path from which to download and run the freshly built installer by using vCommander variables in your completion workflow.


Creating the Completion Workflow

Finally, create the Completion Workflow to install the build on the deployed VM.

  1. Under the Configuration menu, choose Service Request Configuration.
  2. Switch to the Completion Workflow tab.
  3. Click Add.
  4. Enter an appropriate name and choose to Apply this workflow: after a VM is deployed. Click Next.
  5. You'll likely want to include steps to Wait for the VM to be ready to install the build upon. In this example, we wait for Guest OS Customization to Complete and Service to obtain IP address and DNS name.


  6. Click Add > Execute Script and configure the step as follows:

    Step Name: Copy Script from Build Directory
    Step Execution: Always execute
    Timeout: 300 (note this is a typical value, and may need to be adjusted based on your environment)
    Script Output: Capture script output as comment
    When Step Fails: Proceed to next workflow step
    Command Line: 

     

    c:\windows\system32\WindowsPowerShell\v1.0\PowerShell.exe Copy-Item \\SOURCE_DIRECTORY\build\#{target.settings.customAttribute['Build']}\installer.exe -Destination c:\installer.exe

     

    Replace SOURCE_DIRECTORY with the root of the share where the builds are generated. The destination argument controls where the file is copied on the deployed VM. Using the command line above, the destination will be the root of C:.

  7. Click Add > Run Program and configure the step as follows:

    Step Name: Run Script to Install
    Step Execution: Always Execute
    Timeout: 300 (note this is a typical value, and may need to be adjusted based on your environment)
    Script Output: Capture script output as comment
    When Step Fails: Proceed to next workflow step
    Command Line:

     

    c:\installer.exe /S

     

    Replace the example above with the location and file name the build was copied to in the previous step. Remember to include any necessary parameter to run the install silently.
  8. Configure any other steps to handle notifications or other activities and click Next.
  9. Choose Apply this workflow to the selected components: and select the components for the Services you named in your edit of the Jenkins script.

  10. Click Next then Finish.


Additional Reference: Jenkins Variables

Jenkins variables for PowerShell that can be passed into vCommander as necessary.

VariableDescription
$ENV:BUILD_NUMBERThe current build number, such as "153"
$ENV:BUILD_IDThe current build ID, such as "2005-08-22_23-59-59" (YYYY-MM-DD_hh-mm-ss)
$ENV:JOB_NAMEName of the project of this build, such as "foo"
$ENV:BUILD_TAGString of "jenkins-${JOB_NAME}-${BUILD_NUMBER}". Convenient to put into a resource file, a jar file, etc for easier identification.
$ENV:EXECUTOR_NUMBERThe unique number that identifies the current executor (among executors of the same machine) that's carrying out this build. This is the number you see in the "build executor status", except that the number starts from 0, not 1.
$ENV:NODE_NAMEName of the slave if the build is on a slave, or "master" if run on master
$ENV:NODE_LABELSWhitespace-separated list of labels assigned to the node.
$ENV:JAVA_HOMEIf your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to include $JAVA_HOME/bin.
$ENV:WORKSPACEThe absolute path of the workspace.
$ENV:HUDSON_URLFull URL of Hudson, like http://server:port/hudson/
$ENV:JENKINS_URLFull URL of Jenkins, like http://server:port/jenkins/
$ENV:BUILD_URLFull URL of this build, like http://server:port/jenkins/job/foo/15/
$ENV:JOB_URLFull URL of this job, like http://server:port/jenkins/job/foo/
$ENV:SVN_REVISIONFor Subversion-based projects, this variable contains the revision number of the module.
$ENV:CVS_BRANCHFor CVS-based projects, this variable contains the branch of the module. If CVS is configured to check out the trunk, this environment variable will not be set.