This module helps you automate change requests in ServiceNow from Continuous Delivery for Puppet Enterprise (CD4PE) pipelines. The module has been tested for compatibility with the following ServiceNow versions:
- Paris
- Quebec
- Rome (recommended)
The intended workflow that this module enables, is as follows:
- Git commit
--triggers-->CD4PE pipeline--creates-->ServiceNow change request - ServiceNow change request goes through internal approval process
- Change request approved
--triggers-->Business Rule--orchestrates-->CD4PE code promotion & deployment
The module consist of two parts:
- A Bolt plan (
servicenow_change_requests::prep_servicenow) that is used to prepare ServiceNow for the integration. - A set of files (in
files/deployments) that provides a custom deployment policy for CD4PE. This content needs to be copied tosite-modules/deploymentsof your control repo, so that CD4PE can use it.
Finally, this README provides the instructions for getting the integration up & running.
These are the minimum requirements for the latest version of the module, see the Compatibility matrix for more specific details.
- Puppet Enterprise 2019.8.x / 2021.x
- CD4PE 4.11.0 or higher
- ServiceNow Paris or higher
To ensure we can automate change requests, some things need to be added to ServiceNow:
- An additional change request category:
Puppet Code - A business rule named
Puppet Code Promotionthat triggers on approvedPuppet Codechange requests, and performs the orchestration against CD4PE (pipeline promotion & approvals of deployments to protected environments) - CD4PE connection information & credentials for the business rule to use
A single plan takes care of setting this up. To run the plan, go to the Plans section in the left navigation bar in Puppet Enterprise. In the "Run a plan" screen, select the servicenow_change_requests::prep_servicenow from the Plan dropdown list. If the plan is not listed, ensure that this module has been added to the Puppetfile of your control repo, and that you have performed a code deployment to your production environment.
The plan requires 2 parameters + authentication info, and has 3 more optional parameters for specific use cases. The 2 required parameters are:
now_endpoint: The reachable FQDN of the ServiceNow instance (just the name is sufficient)cd4pe_endpoint: The publicly reachable FQDN of the CD4PE server (just the name, not the full URL)
For authentication info, either a username + password must be set, or a valid OAuth token can be used:
admin_user: The username of an administrator in ServiceNow, to make the necessary changesadmin_password: The password of the specified admin_useroauth_token: An OAuth token for accessing ServiceNow, instead of using username + password
For example, to configure the ServiceNow instance https://dev365937.service-now.com to integrate with a CD4PE server at https://puppet-cd4pe.mycompany.com, specify the parameters as follows:
now_endpoint = dev365937.service-now.comcd4pe_endpoint = puppet-cd4pe.mycompany.comadmin_user = adminadmin_password = <password>
or, with an OAuth token:
now_endpoint = dev365937.service-now.comcd4pe_endpoint = puppet-cd4pe.mycompany.comoauth_token = <token>
If you are running a CD4PE version lower than 4.5.0, you will need to set the br_version parameter to ensure a compatible version of the Business Rule gets installed in ServiceNow:
br_version = 0.2.2
Omit this parameter when you are running CD4PE 4.5.0 or above, which will install version 0.2.3 of the Business Rule, which is compatible with CD4PE 4.5.0.
The optional parameters cd4pe_https and cd4pe_port can be used to connect to a CD4PE server on a different port, or via http. For example, to configure the ServiceNow instance https://dev365937.service-now.com to integrate with a CD4PE server at http://puppet-cd4pe.mycompany.com:8080, specify the parameters as follows:
now_endpoint = dev365937.service-now.comadmin_user = adminadmin_password = <password>cd4pe_endpoint = puppet-cd4pe.mycompany.comcd4pe_https = falsecd4pe_port = 8080
The optional parameter connection_suffix can be used to integrate multiple CD4PE installations with a single ServiceNow instance. By default, the plan will create a Puppet_Code Connection Alias in ServiceNow, linked to a Puppet Code Connection and a Puppet Code Credential. This is great for when you have a single CD4PE installation. If you have 1 CD4PE installation, you don't need to specify the connection_suffix parameter.
To handle the multiple CD4PE installations for ServiceNow to interact with, a separate set of connections & credentials needs to be created in ServiceNow for each CD4PE instance. To let the plan do so, specify an appropriate suffix for this parameter. For example, to setup the integration for a secondary CD4PE installation used for "QA", specify connection_suffix = QA. This will create the following in ServiceNow:
- A
Puppet_Code_QAConnection Alias - A
Puppet Code Connection - QAConnection, linked to thePuppet_Code_QAalias - A
Puppet Code Credential - QACredential, linked to thePuppet_Code_QAalias
The plan will create a dummy credential in ServiceNow, for the user change.me@company.com. After running the plan for the first time, you need to go into ServiceNow and change it to the actual credential info:
- In the ServiceNow navigation bar on the left, type
credentialsin the top filter field. - In the shown results, select
Credentialsbelow theConnections & Credentialssection - Click on the credential to change. By default this is named
Puppet Code Credentials. If you specified aconnection_suffixin the plan above, the credential entry will have this suffix. - Change
change.me@company.comto the actual name of the account in CD4PE you want to use for promoting code and approving deployments to protected environments. It's recommended to create a dedicated account in CD4PE for this purpose. - Update the password to the correct value for the account you specified in the previous step
- Click the
Updatebutton on the lower left part of the form to save the changes.
Once ServiceNow has been prepared, we can setup the integration in CD4PE. This integration makes use of CD4PE's Impact Analysis feature, to determine which nodes are affected by a Puppet code change. A typical pipeline might look like this before the integration:
In this pipeline, the Impact Analysis has been configured to analyse the
productionenvironment.
With the ServiceNow integration, we will add a step between the "Impact Analysis" and the "Deploy to Production" stages. This step will take the output of the "Impact Analysis" step, and create a ServiceNow change request from the data. Upon approval of the change request in ServiceNow, a business rule runs in ServiceNow that promotes the pipeline to the next stage ("Deploy to Production"). If any subsequent stages require deployment approvals, ServiceNow will monitor them and approve the deployments as necessary.
With the added stage, the pipeline looks like this:
The added stage uses a custom deployment policy named deployments::servicenow_integration. We need to make this custom deployment policy available to CD4PE first. To do so:
- Copy the
deploymentsdirectory, found in thefilesdirectory of this module, into thesite-modulesdirectory of your control repo. If your control repo still uses asitedirectory (instead ofsite-modules), then copy thedeploymentsdirectory into thesitedirectory. - We recommend you perform step 1 in the
masterbranch of your control-repo, and then let CD4PE promote these changes to your other branches, all the way into production. Once thedeploymentsdirectory is deployed into production, your CD4PE instance should be able to find thedeployments::servicenow_integrationcustom deployment policy.
Once the custom deployment policy is available, add it to your master pipeline:
- Click on the
...icon of yourDeploy to Productionstage and clickAdd a stage before - Enter
ServiceNow Change Requestas the Stage Name - Select your Production environment as the target (this setting has no effect in practice for this particular custom deployment policy)
- Click the
Custom deployment policiesradio button - Select the
deployments::servicenow_integrationpolicy - Set the parameters for the policy:
now_endpoint: the FQDN of your ServiceNow instance (e.g.dev-365937.service-now.com)now_username: the username to authenticate with ServiceNow (e.g.admin)now_password: the password to authenticate with ServiceNow (e.g.P@ssw0rd!)now_oauth_token: an OAuth token for ServiceNow, instead of using username + password (if you set an OAuth token, it will be used instead of username + password)stage_to_promote_to: the name of the stage to promote to, when approved (e.g.Deploy to Production)
- If desired, set (some of the) optional parameters for the policy:
max_changes_per_node: how many resources per node may change before CD4PE recommends this code change warrants more scrutiny (defaults to10)report_stage: name of the stage that performs the Impact Analysis (defaults toImpact Analysis). Set this parameter if your IA stage is not named "Impact Analysis"!assignment_group: the group in ServiceNow to which the change is assigned (defaults toChange Management)connection_alias: the name of the ServiceNow connection alias that should be used for orchestration after the change request is approved (defaults toPuppet_Code)auto_create_ci: set totrueto automatically create CI's in ServiceNow for nodes identified as affected by Impact Analysis, if those nodes do not exist as CI's in ServiceNow (defaults tofalse)proxy_host: fqdn of the proxy server to use for outbound communications to ServiceNow. Only set this parameter if you need to use a proxy server. Note that the proxy server must not request authentication.proxy_port: port to use on the proxy server, if configured inproxy_host.attach_ia_csv: set totrueto automatically attach a CSV export of the Impact Analysis to the ServiceNow Change Request.
- Click
Add stageto complete the wizard. - Click the
Auto-promotecheckbox between the "Impact Analysis" and the "ServiceNow Change Request" stage. - Ensure no auto-promotion occurs between the "ServiceNow Change Request" stage and the "Deploy to Production" stage.
When preparing ServiceNow, you configured a CD4PE account (changing the dummy change.me@company.com account name). This account needs to:
- Exist in CD4PE
- Be a member of the workspace(s) that have pipelines that integrate with ServiceNow
- Have at least
ListandEditpermissions onControl ReposandModulesin the workspace(s) - If using protected environment, the account must be a member of the approval group for that protected environment.
Once the above steps have been completed, make a Puppet code change in your master branch to verify the integration works. The CD4PE pipeline should trigger, and the last step should be the ServiceNow Change Request. Once that step has successfully completed:
- Navigate to the Open Changes in ServiceNow
- A new change request should be created, the "Short description" always starts with
Puppet Code -followed by the commit message and the stage to promote to - Open the change request and note the information it contains:
- The category is set to
Puppet Code - The "Short description" and "Description" have been filled in with information from the code commit
- The "Assignment group" has been configured
- The "Risk and impact analysis" field in the "Planning" section has been filled in with a link to the CD4PE Impact Analysis, and a summary report of the results
- The "Close notes" field in the "Closure information" section contains a hash of all the relevant data to automate the CD4PE pipeline upon approval of the change request
- The "Affected CIs" table shows the records of nodes affected by the change (requires the CI's to exist in ServiceNow, or for the
auto_create_ciparameter to be enabled in the custom deployment policy)
- The category is set to
- Approve the change request (both from the Assignment group and the CAB)
- Once fully approved, click the
Implementbutton on the top right to immediately start implementation of the change. This action triggers the business rule that runs asynchronously - Switch to the "Notes" section of the change request to see live updates of the orchestration as it happens. If an error does occur, you can see information about it in the
Script Log Statementsarea of ServiceNow. - Check back in CD4PE to see that the pipeline has been promoted. If the deployment to the production environment was a protected environment, ServiceNow will also attempt to automatically approve this deployment. Of course you need to ensure that the credentials you have configured in ServiceNow have the appropriate permissions in CD4PE to do so.
- Switch back to the change ticket in ServiceNow and navigate to the
Change Taskstable. Notice that 2 change tasks have been created (ImplementandPost implementation testing). Note that if the orchestration completed successfully, the Notes will say that the Change Tasks will be closed, and the Close Code for the ticket will be set to successful. Refresh the page of the ticket to verify that is indeed the case. - The change request is now in the
Reviewstate, and can be closed by clicking theClosebutton on the top right.

