vcommander servicenow integration guide -...

58
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

Upload: lamthu

Post on 16-Jun-2018

335 views

Category:

Documents


2 download

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