vcommander servicenow integration guide -...
TRANSCRIPT
vCommander
ServiceNow
Integration Guide
© 2016, Embotics Corporation, all rights reserved. Information described herein is furnished for informational use only, is subject
to change without notice, and should not be taken as a guarantee, commitment, condition or offer by Embotics. Embotics, the Embotics logo, and all other Embotics product names and logos are trademarks or registered trademarks of Embotics and/or its
subsidiaries in the United States and other countries. All other product or company names are property of their respective owners.
Document version 1.0
ServiceNow Integration Version 1.0
vCommander ServiceNow
Integration Guide
Integration Guide
Version 1.0
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 1 Documentation
Executive Summary
Embotics® vCommander™ provides self-service, provisioning automation and tracking of
VM asset data across private, public and hybrid clouds in single or multi-tenant
environments. ServiceNow® provides a primary system of record for all service ticketing
and a configuration management database (CMDB).
Integration between these two best-of-breed solutions yields real-time, accurate reporting
of key organizational information for assets, service level agreements and costs. It also
allows consumers of IT services to interact with IT/IS departments in a familiar manner
optimized for their use, thereby maximizing efficiency of service delivery and business
agility.
The functionality provided covers three key uses cases:
1. Synchronizing vCommander asset data into the ServiceNow CMDB in real-time when
new service requests or change requests are fulfilled, as well as scheduling updates
reflecting ongoing environmental changes originating outside vCommander.
2. Creating and updating tickets in ServiceNow as vCommander new service requests or
change requests are initiated in vCommander and processed.
3. Initiating requests in ServiceNow and fulfilling them with vCommander.
Not all organizations will need all three integration points, and some may choose to
implement the integration in stages. For these reasons, this document is subdivided into
sections addressing the individual use cases.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 2 Documentation
Contents
Executive Summary .............................................................................. 1
Requirements....................................................................................... 5
Before You Begin ..................................................................................................... 5
Creating an Integration User ..................................................................................... 5
vCommander Custom Attributes ................................................................................ 6
Synchronizing VM Asset Data ................................................................. 7
Mapping Metadata ................................................................................................... 8
vCommander Scripts ................................................................................................ 8
vCommander Workflows ........................................................................................... 9
New Service Requests .......................................................................................................10
Change Requests ..............................................................................................................11
Decommissioning Requests ................................................................................................12
Creating the Scheduled Task ................................................................................... 14
Creating and Updating ServiceNow Tickets ............................................ 17
vCommander Scripts .............................................................................................. 17
Creating Forms ..................................................................................................... 19
Configuring Workflow Steps .................................................................................... 20
ServiceNow Incidents – vCommander New Requests .............................................................20
ServiceNow Incidents – vCommander Change Requests ........................................................22
ServiceNow Incidents – vCommander Decommissioning Requests...........................................25
ServiceNow Requests – vCommander New Requests .............................................................27
ServiceNow Requests – vCommander Change Requests.........................................................29
ServiceNow Requests – Decommissioning Requests ..............................................................31
Requesting Services within ServiceNow ................................................. 34
vCommander Scripts .............................................................................................. 34
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 3 Documentation
Reproducing the Service Catalog in ServiceNow ........................................................ 36
Creating the REST Messages ................................................................................... 40
Creating the ServiceNow Workflows ......................................................................... 48
Expanding This Solution ...................................................................... 56
Executive Summary .............................................................................. 1
Requirements....................................................................................... 4
Before You Begin ..................................................................................................... 4
Creating an Integration User ..................................................................................... 4
vCommander Custom Attributes ................................................................................ 5
Synchronizing VM Asset Data ................................................................. 6
Mapping Metadata ................................................................................................... 7
vCommander Scripts ................................................................................................ 7
vCommander Workflows ........................................................................................... 8
New Service Requests ........................................................................................................ 9
Change Requests ..............................................................................................................10
Decommissioning Requests ................................................................................................11
Creating the Scheduled Task ................................................................................... 13
Creating and Updating ServiceNow Tickets ............................................ 16
vCommander Scripts .............................................................................................. 16
Creating Forms ..................................................................................................... 18
Configuring Workflow Steps .................................................................................... 19
ServiceNow Incidents – vCommander New Requests .............................................................19
ServiceNow Incidents – vCommander Change Requests ........................................................21
ServiceNow Incidents – vCommander Decommissioning Requests...........................................24
ServiceNow Requests – vCommander New Requests .............................................................26
ServiceNow Requests – vCommander Change Requests.........................................................28
ServiceNow Requests – Decommissioning Requests ..............................................................30
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 4 Documentation
Requesting Services within ServiceNow ................................................. 33
vCommander Scripts .............................................................................................. 33
Reproducing the Service Catalog in ServiceNow ........................................................ 35
Creating the REST Messages ................................................................................... 39
Creating the ServiceNow Workflows ......................................................................... 47
Expanding This Solution ...................................................................... 55
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 5 Documentation
Requirements
Find below the requirements necessary to fulfill the complete integration as described in this
document.
Embotics vCommander 5.7.6 or later
Embotics vCommander REST API Powershell client & libraries
PowerShell v4 installed on the vCommander application server
vCommander Scripts
Encrypted vCommander credentials with REST API access
ServiceNow credentials with REST API access
Before You Begin
As when making any substantial change to a production system, Embotics strongly
recommends taking measures to ensure a successful roll-back is possible in case
unexpected failures occur. These include making sure there are current backups of the
vCommander SQL database and snapshots of the vCommander application server.
Additionally, you may want to implement and test the integration in a staging environment
to make sure it operates as expected prior to putting it into production. Embotics provides
customers with staging or lab licenses upon request. Contact your Customer Advocate for
more information about these limited, supplementary licenses.
Creating an Integration User
As a best practice, you should create a specific user account to handle the integration
activity. Doing so makes it easy to track actions undertaken by the integration by parsing
vCommander events for the account, and provides an account to use for form assignment.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 6 Documentation
In most cases, simply using a local
vCommander account with the User
role will be sufficient. However, you
can use directory services (AD/LDAP)
accounts and/or Service Portal
accounts as necessary.
Provide appropriate access rights to
see your infrastructure.
Provide a name that will be
recognizable in events and logs as
being the integration user.
Provide an email address that will
contact an appropriate person should
there be any request failures.
Similarly, Embotics recommends that the ServiceNow credentials used are dedicated to the
integration and easily identifiable. This will help distinguish between actions undertaken by
automation versus those by human users.
vCommander Custom Attributes
This integration automatically creates several vCommander custom attributes in order to
cross-reference unique identifiers between vCommander and ServiceNow. When these are
created, the description fields include a warning not to delete them.
If these custom attributes are deleted, the next time vCommanders contact ServiceNow,
duplicate records will be created. As such it is imperative that all vCommander
administrators understand that they must not delete custom attributes or manually adjust
these custom attribute values for VMs. All activity with these attributes must be handled
exclusively by the integration's automation.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 7 Documentation
Synchronizing VM Asset Data
This function of the integration ensures that updates to the configuration management
database occur. This data includes a configurable range of information such as VM name,
DNS/IP, owner, organization, cloud, quota, CPU, memory, storage, instance type, cost, and
even custom attributes you've added to vCommander like backup schedule, SLA and
workload type.
There are two scenarios here: 1) In-process changes made in vCommander, and 2) Out-of-
process changes made directly in the underlying virtual/cloud environment.
When in-process changes are made, a step in the vCommander workflow automatically
creates or updates the configuration item in the CMDB.
For out-of-process changes, a trigger is needed to update the records. To manage this, a
script is configured to run on the vCommander application server on a schedule you define,
to make sure both systems are up to date with all your VM asset data. In this section, the
procedure to use the Windows Task Scheduler as a trigger is presented, but other similar
scheduling mechanisms are equally suitable.
Embotics suggests running the scheduled task during a weekly period of low activity, as the
enumeration process to capture VMs not created in vCommander takes some time. Under
typical conditions, the process takes around 20 minutes per 500 VMs.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 8 Documentation
Mapping Metadata
Before adding the integration scripts to vCommander workflows and scheduling Windows
Tasks, you must decide what VM metadata you want to synchronize between vCommander
and ServiceNow and update the vCommander scripts accordingly.
In this document, our examples use the following metadata:
Request ID
CPU Count
Memory Size in GB
Storage Size in GB
VM Name
DNS Name
IP Address
MAC Address
Guest OS
Running State
Primary Owner Email
Organization
Yearly Cost
Published Service Name
(Custom Attribute) Environment
(Custom Attribute) Project Code
Other metadata may also be collected and synchronized in your environment by updating
the scripts and changing the workflow step command lines to provide the associated data
using vCommander variables.
vCommander Scripts
You should already have downloaded and extracted the scripts to your vCommander
application server as detailed in the Requirements section. Embotics recommends storing all
scripts called by vCommander in a single location, using sub-folders to identify the functions
of particular scripts. With the scripts used for this portion of the integration extracted to C:
on the vCommander server, the file system will look like this:
C:\scripts\snow\cmdb\ServiceNow_CMDB_Decomission.ps1
C:\scripts\snow\cmdb\ServiceNow_CMDBSync.ps1
C:\scripts\snow\cmdb\ServiceNow_CreateUpdateCMDB.ps1
All of the scripts covered in this section require minor edits before they will work in your
system.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 9 Documentation
Table: Editable Script Content
Setting Description
$vCommanderServer The hostname or IP address of the
vCommander server.
$CredFile The credentials file which handles access to
your vCommander. For more details, refer to
this knowledgebase article.
$SnowInstance The name of your ServiceNow instance.
$SNcred The credentials file which handles access to
your ServiceNow instance. The user must
have permission to use the ServiceNow API
and access to perform any function via the
API you are automating.
Embotics recommends that you start with
full administrative access and then reduce
permission until you have the minimal
working set required.
Additionally, you can comment out the following lines to prevent creation of a text log in the
specified directory. The logs are overwritten with each run of the script.
vCommander Workflows
In-process changes occur when vCommander users request new services, request changes
to existing services, or decommission existing services. Execute Script steps in the
associated vCommander completion workflows update the ServiceNow CMDB in real-time.
The step to update the ServiceNow CMDB is always configured the same way, no matter in
which completion workflow it is being created. However, with new service requests in
vCommander, the completion workflow is assigned to components, whereas change
requests and decommissioning requests have the completion workflow assigned to the
forms.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 10 Documentation
New Service Requests
Add an Execute Script step to the completion workflow for new service requests as follows:
Step Name: Update ServiceNow CMDB
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\cmdb\ServiceNow_CreateUpdateCMDB.ps1 #{target.id}
Then assign the completion workflow to all components you want registered in the
ServiceNow CMDB when they get deployed, or choose to make it the default workflow so
that all deployments not specifically assigned another completion workflow are registered.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 11 Documentation
Change Requests
Add an Execute Script step to the completion workflow for change requests as follows:
Step Name: Update ServiceNow CMDB
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 12 Documentation
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\cmdb\ServiceNow_CreateUpdateCMDB.ps1 #{target.id}
Then assign the completion workflow to your change request forms:
Decommissioning Requests
Add an Execute Script step to the completion workflow for decommissioning requests as
follows:
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 13 Documentation
Step Name: Update ServiceNow CMDB
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\cmdb\ServiceNow_CMDB_Decommission.ps1 #{target.id}
Then assign the completion workflow to your decommissioning forms:
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 14 Documentation
Creating the Scheduled Task
The integration uses Windows Task Scheduler to run the synchronization script which
captures out-of-process changes. Other similar scheduling mechanisms are equally suitable.
1. Log in to the vCommander application server as a Windows administrator and launch
Task Scheduler.
2. In the Actions pane, click Create Basic Task.
3. Provide a Name and Description. Click Next.
4. Choose the Trigger and click Next.
Embotics suggests running this scheduled task weekly during a period of low activity,
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 15 Documentation
as the enumeration process to capture VMs not created in vCommander takes some
time. Under typical conditions, the process takes around 20 minutes per 500 VMs.
5. Set additional scheduling options and click Next.
6. Choose Start a program as your action and click Next.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 16 Documentation
7. Configure the next page as follows then click Next:
Program/script: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Add arguments (optional): C:\Scripts\snow\cmdb\ServiceNow_CMDBSync.ps1
8. Click Finish.
Following the run of the scheduled task, ServiceNow is updated with the complete asset
information available in vCommander.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 17 Documentation
Creating and Updating ServiceNow Tickets
This portion of the integration creates a new tracking ticket in ServiceNow using requests,
incidents or both whenever a request is made in vCommander. This includes new service
requests, change requests and decommissioning requests. When the request is fulfilled, the
ServiceNow request or incident is updated with all the relevant details and then closed.
This means ServiceNow retains an authoritative history of all requests, including those
initiated by vCommander users and via integration with other automated systems such as
Jenkins.
vCommander Scripts
You should already have downloaded and extracted the scripts to your vCommander
application server as detailed in the Requirements section. Embotics recommends storing all
scripts called by vCommander in a single location, using sub-folders to identify the functions
of particular scripts. With the scripts used for this portion of the integration extracted to C:
on the vCommander server, the file system will look like this:
C:\scripts\snow\incident\ServiceNow_CloseIncident.ps1
C:\scripts\snow\incident\ServiceNow_NewChangeRequest.ps1
C:\scripts\snow\incident\ServiceNow_NewIncident.ps1
C:\scripts\snow\incident\ServiceNow_SetAttrib.ps1
C:\scripts\snow\request\ServiceNow_CloseRequest.ps1
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 18 Documentation
C:\scripts\snow\request\ServiceNow_NewChangeRequest.ps1
C:\scripts\snow\request\ServiceNow_NewRequest.ps1
C:\scripts\snow\request\ServiceNow_SetAttrib.ps1
Your solution may use only the scripts for incidents, only the scripts for requests, or both.
However you end up configuring the solution, all of the scripts covered in this section
require minor edits before they will work in your environment.
Table: Editable Script Content
Setting Description
$vCommanderServer The hostname or IP address of the
vCommander server.
$CredFile The credentials file which handles access to
your vCommander. For more details, refer to
this knowledgebase article.
$SnowInstance The name of your ServiceNow instance.
$SNcred The credentials file which handles access to
your ServiceNow instance. The user must
have permission to use the ServiceNow API
and access to perform any function via the
API you are automating.
Embotics recommends that you start with
full administrative access and then reduce
permission until you have the minimal
working set required.
Additionally, you can comment out the following lines to prevent creation of a text log in the
specified directory. The logs are overwritten with each run of the script.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 19 Documentation
Creating Forms
In vCommander, forms dictate what information is required when a request is made. When
automating an integration that submits requests, Embotics recommends designing forms
that can be explicitly assigned to the integration user account. In this manner you make
sure that changes introduced to the forms for your human users do not disrupt your
automation.
The forms must include controls for each of the custom attributes which must be selected as
part of the request process. Edit each control added to the form to mark it as required.
In order to have records for VMs changed or decommissioned in vCommander updated in
ServiceNow, you must also make sure that your change request and decommissioning forms
are available to the vCommander user handling the integration.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 20 Documentation
Configuring Workflow Steps
In this section, the steps which must be added to vCommander workflows are described.
These steps are specific to the ServiceNow operations and are intended to be used
alongside the other steps dictated by your business and technical requirements.
ServiceNow Incidents – vCommander New Requests
Add an Execute Script step in your approval workflow for new requests as follows. This
will register the deployment as an incident in ServiceNow:
Step Name: Create Incident in ServiceNow
Step Execution: Always Execute
Timeout: 200 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line:
powershell.exe c:\Scripts\snow\incident\ServiceNow_NewIncident.ps1
#{Request.ID} #{request.services[1].settings.primaryOwner.email}
#{request.services[1].settings.customAttribute['Environment']}
#{request.cost.yearly} #{request.services[1].publishedName}
#{request.services[1].settings.cpuCount}
#{request.services[1].settings.memory.gb}
#{request.services[1].settings.storage.gb}
#{request.services[1].settings.customAttribute['Project Code']}
Then add the following Execute Script steps in your completion workflow for new
requests to synchronize data between the systems and close the ServiceNow incident once
deployments have been completed. The steps must appear in the order presented below,
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 21 Documentation
but may be used with other workflow steps at your discretion. Steps that change the VM
configuration should all be completed prior to these steps executing.
Step Name: Set ServiceNow Attributes
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\incident\ServiceNow_SetAttrib.ps1 #{Request.ID}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 22 Documentation
Step Name: Close ServiceNow Incident
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\scripts\incidents\ServiceNow_CloseIncident.ps1 #{Request.ID}
ServiceNow Incidents – vCommander Change Requests
Add Execute Script steps in your approval workflow for change requests as follows.
This will register the change as an incident in ServiceNow:
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 23 Documentation
Step Name: Update ServiceNow
Step Execution: Always execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\incident\ServiceNow_NewChangeRequest.ps1 #{Request.ID}
Associate the workflow with your change request form.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 24 Documentation
Then add the following Execute Script step in your completion workflow for change
requests to synchronize data between the systems and close the ServiceNow incident once
changes have been completed.
Step Name: Close ServiceNow Incident
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\scripts\snow\incident\ServiceNow_CloseIncident.ps1 #{Request.ID}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 25 Documentation
ServiceNow Incidents – vCommander Decommissioning Requests
When a VM is decommissioned in vCommander, a step in your approval workflow for
change requests registers the incident in ServiceNow:
Step Name: Update ServiceNow
Step Execution: Always execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\incident\ServiceNow_NewChangeRequest.ps1 #{Request.ID}
Associate the workflow with your decommissioning form.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 26 Documentation
Finally, add the following step in the completion workflow applied to the
decommissioning form to close the ticket:
Step Name: Close ServiceNow Ticket
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 27 Documentation
Command Line: powershell.exe c:\Scripts\cmdb\ServiceNow_CMDB_Decomission.ps1 #{target.id}
ServiceNow Requests – vCommander New Requests
Configure an Execute Script workflow step in your approval workflow for new requests
as follows. This will register the deployment as a request in ServiceNow:
Step Name: Open ServiceNow Request
Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line:
powershell.exe c:\Scripts\snow\request\ServiceNow_NewRequest.ps1
#{Request.ID} #{request.services[1].settings.primaryOwner.email}
#{request.services[1].settings.customAttribute['Environment']}
#{request.cost.yearly} #{request.services[1].publishedName}
#{request.services[1].settings.cpuCount}
#{request.services[1].settings.memory.gb}
#{request.services[1].settings.storage.gb}
#{request.services[1].settings.customAttribute['Project Code']}
Then add the following Execute Script steps in your completion workflow for new
service requests to close the ServiceNow request once your deployments have been
completed. The steps must appear in the order presented below, but may be used with
other workflow steps at your discretion. Steps that change the VM configuration should all
be completed prior to these steps executing.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 28 Documentation
Step Name: Set ServiceNow Attributes
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\request\ServiceNow_SetAttrib.ps1 #{Request.ID}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 29 Documentation
Step Name: Close ServiceNow Request
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\request\ServiceNow_CloseRequest.ps1 #{Request.ID}
ServiceNow Requests – vCommander Change Requests
Add execute script steps in your approval workflow for change requests as follows. This
will register the change as a request in ServiceNow:
Step Name: Update ServiceNow
Step Execution: Always execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\request\ServiceNow_NewChangeRequest.ps1 #{Request.ID}
Associate the workflow with your change request form.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 30 Documentation
Then add the following Execute Script steps in your completion workflow for change
requests to synchronize data between the systems and close the ServiceNow request once
your changes have been completed. The steps must appear in the order presented below,
but may be used with other workflow steps at your discretion. Steps that change the VM
configuration should all be completed prior to these steps executing.
Step Name: Close ServiceNow Request
Step Execution: Always Execute
Timeout: 300 seconds
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 31 Documentation
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\scripts\snow\request\ServiceNow_CloseIncident.ps1 #{Request.ID}
ServiceNow Requests – Decommissioning Requests
When a VM is decommissioned in vCommander, an Execute Script step in your approval
workflow for change requests registers the request in ServiceNow:
Step Name: Update ServiceNow
Step Execution: Always execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
Command Line: powershell.exe c:\Scripts\snow\requests\ServiceNow_NewChangeRequest.ps1 #{Request.ID}
Associate the workflow with your decommissioning form.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 32 Documentation
Finally, add the following Execute Script step in the completion workflow applied to the
decommissioning form to close the ticket:
Step Name: Close ServiceNow Ticket
Step Execution: Always Execute
Timeout: 300 seconds
Script Output: Capture script output as comment
When Step Fails: Mark workflow step as failed: do not proceed
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 33 Documentation
Command Line: powershell.exe c:\Scripts\snow\request\ServiceNow_CloseRequest.ps1 #{target.id}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 34 Documentation
Requesting Services within ServiceNow
Initiating vCommander service requests from within ServiceNow is useful when users are
already accustomed to using ServiceNow for this purpose. To set this up, the service catalog
items you want to make available must be recreated in ServiceNow.
Once the service catalog items are exposed, ServiceNow users request the service and
ServiceNow workflow processes determine whether the request may proceed. Next,
ServiceNow calls into vCommander to fulfill the request. You may include additional steps in
the approval workflow assigned to the ServiceNow user, or simply assign the user an
approval workflow with no steps set to automatically deploy.
Once deployment is finished, steps in the completion workflow call in to ServiceNow to
update the request or incident.
vCommander Scripts
You should already have downloaded and extracted the scripts to your vCommander
application server as detailed in the Requirements section. Embotics recommends storing all
scripts called by vCommander in a single location, using sub-folders to identify the functions
of particular scripts. With the scripts used for this portion of the integration extracted to C:
on the vCommander server, the file system will look like this:
C:\scripts\Snow_Catalog\vCommander_GetServiceXML.ps1
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 35 Documentation
The script requires minor edits before it will work in your environment. In order to make the
changes, you need to know the display name of the service catalog entry you are
duplicating. In this example, we use a service with the display name
ServiceNowScenario3_Windows.
The edits are as follows:
Table: Editable Script Content
Setting Description
$ServiceCatalogName This is the display name of the service as
listed in its service catalog entry.
$vCommanderServer The hostname or IP address of the
vCommander server.
$CredFile The credentials file which handles access to
your vCommander. For more details, refer to
this knowledgebase article.
Unlike the other scripts available for the ServiceNow integration, this script contains no
logging capabilities. Any errors will be represented in the main vcommander.log file. This
script is run once for each vCommander service that will be duplicated in ServiceNow.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 36 Documentation
Reproducing the Service Catalog in ServiceNow
Before users can request services directly in ServiceNow, the vCommander service catalog
entries you want to make available must be reproduced in ServiceNow.
To ensure that the form matches the vCommander New Request Form assigned to the
integration user, create ServiceNow variables that align to vCommander custom attributes,
matching values exactly across both systems.
1. Log in to ServiceNow and browse to Catalog Definitions > Maintain Items. Click
New.
2. Fill out the basic information for the catalog definition. Note that cost information will
be overwritten later in the process, and a workflow will be assigned later.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 37 Documentation
3. At the bottom of the page, switch to the Variable Sets tab. Click New.
4. Enter vCommander Variable Set as the Name, and set the Layout to 2 Columns
Wide, alternating sides.
5. Under the Variables tab, click New and configure the following at a minimum,
completing other fields as appropriate for your configuration:
Type: Select Box
Mandatory: Enabled
Active: Enabled
Question: How much storage?
Name: requested_GB
Question Choices (Text/Value):
Text Value
Please Select 0
40GB 40000000
60GB 60000000
80GB 80000000
100GB 100000000
6. Click New and configure the following:
Type: Single Line Text
Mandatory: Enabled
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 38 Documentation
Active: Enabled
Question: Who will be the primary owner of this virtual service?
Name: primary_owner
7. Click New and configure the following:
Type: Select Box
Mandatory: Enabled
Active: Enabled
Question: Please specify the environment
Name: requested_env
Question Choices (Text/Value):
Text Value
Please Specify 0
Staging staging
Sandbox sandbox
Production production
Development development
8. Click New and configure the following:
Type: Select Box
Mandatory: Enabled
Active: Enabled
Question: How much RAM?
Name: requested_mem
Question Choices (Text/Value):
Text Value
Please Specify 0
1GB 1024
2GB 2048
4GB 4096
9. Click New and configure the following:
Type: Select Box
Mandatory: Enabled
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 39 Documentation
Active: Enabled
Question: How many vCPUs?
Name: requested_CPU
Question Choices (Text/Value):
Text Value
Please Specify 0
1 1
2 2
4 4
10. Click New and configure the following:
Type: Select Box
Mandatory: Enabled
Active: Enabled
Question: Please specify the project code
Name: project_code
Question Choices (Text/Value):
Text Value
As appropriate, matching
vCommander custom
attribute.
Matches the associated text label.
11. Switch to the Catalog Client Scripts.
12. Click New and configure the following, then click Submit:
Name: email check
Applies to: a variable set
Active: Enabled
UI Type: both
Type: onChange
Variable Set: vCommander Variable Set
Variable Name: primary_owner
Applies on Catalog Item view: Enabled
Applies on Requested Items: Enabled
Applies on Catalog Tasks: Enabled
Script:
function onChange(control, oldValue, newValue, isLoading) {
if (isLoading || newValue == '') {
g_form.hideErrorBox('primary_owner');
return;
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 40 Documentation
}
var valid = validateEmail(newValue);
g_form.hideErrorBox('primary_owner');
if (!valid)
g_form.showErrorBox('primary_owner', getMessage('Invalid email
address'));
else
g_form.hideErrorBox('primary_owner');
}
function validateEmail(primary_owner) {
var re =
/^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+)*)|(\".+\"))@
((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-
0-9]+\.)+[a-zA-Z]{2,}))$/;
return re.test(primary_owner); }
Creating the REST Messages
The first outbound REST call runs a check to confirm that communications with
vCommander are normal. This is accomplished by generating a vCommander API call to
retrieve the status of a service request by its ID.
1. Log in to ServiceNow and browse to System Web Services > Outbound > REST
Message. Click New.
2. Enter the Name vCommander Check Status and optionally provide the Description
Check to see whether the request has completed.
3. Click to unlock the editable Endpoint field and enter
https://proxyvc.vcommander.com/webservices/services/rest/v2/requests/${request
_id}/rservices. Click to lock the field.
4. Under the Authentication tab, set the Authentication type to Basic.
5. Beside Basic auth profile click . Click New.
6. Provide an appropriate label for the credentials in the Name field, and then enter the
Username and Password for the vCommander user account created for the
integration. Click Submit.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 41 Documentation
7. Click Submit.
8. You are returned to the REST Messages listing. Click vCommander Check Status.
9. In the HTTP Methods section, select all the methods except get and click Actions
on selected rows… > Delete.
10. Click Delete to confirm the action.
11. Under HTTP Methods, click get.
12. Under the Authentication tab, set the Authentication type to Basic.
13. Beside Basic auth profile, click .
14. Click vCommander.
15. Under the Related Links section, click Auto-generate variables.
16. In the Variables Substitutions tab, click request_id.
17. For the Test Value, enter the ID of a request that exists in vCommander in a
COMPLETED state, so that this check will succeed and allow ServiceNow workflows to
proceed.
18. Click Update.
19. To confirm, click vCommander Check Status.
20. Under the HTTP Methods section, click get.
21. Under Related Links, click Test.
22. Scroll down in the response field and confirm that the value for the <state> element
is COMPLETED, matching what you see for the request in vCommander.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 42 Documentation
If the results match, communication is successful, and you can proceed with creating
other REST messages in ServiceNow.
Next, outbound REST calls must be created for each vCommander service you want to make
available in ServiceNow. As a first step, we must first run the script to retrieve the service
definition from vCommander.
To do so, execute the vCommander_GetServiceXML.ps1 script.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 43 Documentation
In the results pane, note the PublishedServiceID. This value is inserted into the endpoints
created in ServiceNow REST messages.
Next, copy the contents of the <PSDeployParamCollection> element and paste these
into a text editor. Referring back to ServiceNow for confirmation of your ServiceNow
variable names, overwrite the value elements in your text file.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 44 Documentation
For example, the variable name requested_CPU will be enclosed between a dollar sign and
curly brackets like so: ${requested_CPU} and then copied into the text file as the value
for the associated element in the service definition.
You must also edit into the XML the name of the storage tier onto which the VMs will be
deployed. This is the case even if you do not have the associated control on your forms.
Do so by editing the value of the <storageTierLabel> element with the matching name,
like so:
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 45 Documentation
These edits are case-sensitive, so be sure to use the text as it appears in ServiceNow
exactly, to prevent failures. Save as a text file named for the service, rather than as XML.
Repeat this process for each service that will be made available.
Now that the communications are confirmed and the edited service definitions are available,
the following procedure provides an example for a creating a service in the ServiceNow
catalog.
1. Log in to ServiceNow and browse to System Web Services > Outbound > REST
Message. Click New.
2. Enter the Name vCommander Windows VM Request. Optionally provide the
Description Requests a configurable Windows VM deployment.
3. Click to unlock the editable Endpoint field, and enter
https://proxyvc.vcommander.com/webservices/services/rest/v2/publishedservices/1
780119/action/submit replacing 1780119 with the correct PublishedServiceID as
noted prior. Click to lock the field.
4. Under the Authentication tab, set the Authentication type to Basic.
5. Beside Basic auth profile, click .
6. Click vCommander and then Submit.
7. You are returned to the REST Messages listing. Click vCommander Windows VM
Request.
8. In the HTTP Methods section, select all the methods except post and click Actions
on selected rows… > Delete.
9. Click Delete to confirm the action.
10. Under HTTP Methods, click post.
11. Under the Authentication tab, set the Authentication type to Basic.
12. Beside Basic auth profile, click .
13. Click vCommander.
14. Switch to the HTTP Request tab.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 46 Documentation
15. Copy the XML contents of the service definition text file into the Content field.
16. Click Update.
17. Under HTTP Methods, click post.
18. Under Related Links, click Auto-generate variables. The Variables
Substitutions tab is populated with all of the configurable values for the service.
19. Click on each value in the list and provide a Test Value. The test values must be
within ranges permitted on the vCommander forms for the service being request.
Additionally, note that memory and hard disk sizes are represented in megabytes.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 47 Documentation
After you submit the last test value, you are returned to the HTTP Method > post
page. Under Related Links, click Test. If everything has been configured correctly,
the results will show a HTTP status 200, and the Response will include the
pertinent details about the vCommander service request which has been generated.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 48 Documentation
Creating the ServiceNow Workflows
This portion of the integration requires that you prepare a ServiceNow workflow for each
vCommander service you make available. Given the extensibility of ServiceNow, there are
many actions you can add to your workflows beyond what is shown here. The example
provided documents only the minimal required steps.
The General properties of the workflow are as follows:
Name: vCommander Windows VM Request
Table: Requested Item [sc_req_item]
Published: Enabled
Note the workflow name. Once you've completed the workflow design, you must return to
the ServiceNow catalog item and assign the workflow by name.
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 49 Documentation
The Stages properties of the workflow are as follows:
As you work in the Drawing Canvas to create the workflow, it's important to remember that
when referring to the variables, you must always maintain case-sensitivity to prevent
failures. The workflow steps are defined as follows:
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 50 Documentation
try {
var r = new sn_ws.RESTMessageV2('vCommander Windows VM Request', 'post');
r.setStringParameter('requested_mem', current.variables.requested_mem);
r.setStringParameter('project_code', current.variables.project_code);
r.setStringParameter('requested_env', current.variables.requested_env);
r.setStringParameter('primary_owner', current.variables.primary_owner);
r.setStringParameter('requested_cpu', current.variables.requested_CPU);
r.setStringParameter('requested_gb', current.variables.requested_GB);
//override authentication profile
//authentication type ='basic'/ 'oauth2'
//r.setAuthentication(authentication type, profile name);
var response = r.execute();
var responseBody = response.getBody();
var httpStatus = response.getStatusCode();
var parser = new JSONParser();
//var parsed = parser.parse(responseBody);
//for (i = 0; parsed.tags.resource.length; i++){
//var id = parsed.tags.resource[i].id;
var xmldoc = new XMLDocument(responseBody);
var str = xmldoc.getNodeText("//id"); // returns the first occurrence of the
node
//Get the RequestID from the response
workflow.scratchpad.id = str;
gs.log (responseBody,"vCommander");
gs.log (workflow.scratchpad.id,"vCommanderID");
}
catch(ex) {
var message = ex.getMessage();
}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 51 Documentation
// This script needs to set answer to 'yes' or 'no' to indicate the state of
the activity.
answer = ifScript();
function ifScript() {
if (JSUtil.notNil(workflow.scratchpad.id)) {
return 'yes';
}
return 'no';
}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 52 Documentation
try {
var r = new sn_ws.RESTMessageV2('vCommander Check Status', 'get');
r.setStringParameter('request_id', workflow.scratchpad.id);
var response = r.execute();
var responseBody = response.getBody();
var httpStatus = response.getStatusCode();
//Check the Body of the result
var xmldoc = new XMLDocument(responseBody);
var str = xmldoc.getNodeText("//state"); // returns the first occurrence of
the node
workflow.scratchpad.state = str;
gs.log (responseBody,"RequestBodyState");
gs.log (workflow.scratchpad.state,"request state");
}
catch(ex) {
var message = ex.getMessage();
}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 53 Documentation
// This script needs to set answer to 'yes' or 'no' or 'complete' to indicate
the state of the activity.
answer = ifScript();
function ifScript() {
if (workflow.scratchpad.state == 'COMPLETED'){
return 'yes';
}
return 'no';
}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 54 Documentation
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 55 Documentation
// This script needs to set answer to 'yes' or 'no' or 'complete' to indicate
the state of the activity.
if (JSUtil.nil(workflow.scratchpad.counter)){
workflow.scratchpad.counter = 0;
}
workflow.scratchpad.counter = parseInt(workflow.scratchpad.counter) + 1;
answer = ifScript();
function ifScript() {
if (parseInt(workflow.scratchpad.counter) >= 60){
return 'no';
}
return 'yes';
}
vCommander ServiceNow Document Version 1.0
Integration Guide ©2016 All rights reserved in all media
www.embotics.com 56 Documentation
Expanding This Solution
The examples in this document provided specific sets of metadata to be exchanged between
vCommander and ServiceNow. However, both systems are highly configurable and present
significant customization opportunities. Not only can the wide variety of information
available in vCommander be synchronized to ServiceNow, but vCommander's custom
attributes also enable an unlimited number of data points.
Additionally, because the integration described here is implemented using existing
vCommander workflows and APIs, it can be repurposed to function with any other asset or
service desk system.
The most important activity in any design process you undertake is preparation of the
requirements. Take the time to sketch out the activity between each system, noting user
actions and results, so that if you would like assistance expanding this solution beyond the
examples provided in this document, you will be able to clearly explain your requirements to
Embotics staff.
Please contact Embotics Technical Support for assistance if you'd like to further customize
the ServiceNow solution provided here, or develop a similar integration.
vCommander
ServiceNow
Integration Guide
© 2016, Embotics Corporation, all rights reserved. Information described herein is furnished for informational use only, is subject
to change without notice, and should not be taken as a guarantee, commitment, condition or offer by Embotics. Embotics, the Embotics logo, and all other Embotics product names and logos are trademarks or registered trademarks of Embotics and/or its
subsidiaries in the United States and other countries. All other product or company names are property of their respective owners.
Document version 1.0
ServiceNow Integration Version 1.0