Cloud Provisioning and Governance and Flow Designer Series : Part 1 - Creating a Subflow for CPG

[brian_quinn]

Introduction

Cloud Provisioning and Governance enables users to quickly standup cloud resources using templates, however in many cases provisioning is only the beginning.  Business processes may need to be executed before a resource is provisioned, after it is provisioned, or even as a lifecycle operation weeks later.  These processes may be within the ServiceNow instance, within the Cloud Provider, or in some third party tool.  This is where the power of Flow Designer and IntegrationHub can be leveraged.  Flow Designer can be used to build automated and reusable flows that can be called by Cloud Provisioning and Governance.  Within these flows integration with third party tools can be quickly configured using IntegrationHub or a custom action can be developed for the highest level of flexibility.  

Cloud Provisioning and Governance can leverage flows in multiple places:

• Immediately before provisioning a template
• Immediately after provisioning a template
• Immediately before de-provisioning a template
• Immediately after de-provisioning a template
• As a Day 2 lifecycle operation on an entire Stack
• As a Day 2 lifecycle operation on an individual Cloud Resource

This article will cover some best practices for creating Flow Designer flows for use in Cloud Provisioning and Governance and walk through a sample flow that includes error handling.  Future articles will cover how to configure Cloud Provisioning and Governance to launch these flows.

Best Practices

• The subflow must have a string input named flowcorrelationid if it is called directly from Cloud Provisioning and Governance
• • When calling the subflow from Cloud Provisioning and Governance, the flowcorrelationid should be populated using the expression "$(Script:CMPFlowStepHandler.generateCorrelationId)"
• Flow results must be populated EXACTLY ONCE
• • Every place flow results are populated, there should be an "End" action immediately afterwards
  • Only the parent subflow called directly from Cloud Provisioning and Governance should populate flow results
• Flow results can be populated using one of the following methods:
• • A custom action that executes a javascript function to populate the flow results
  • • Sample code

    • • new sn_cmp.CMPFlowDesignStepHandler().populateFlowResult(correlationid, inputs);​

      • The correlationid variable should be a string value
      • The inputs variable should be a stringified JSON object containing the following keys: error, log, output, correlationid
  • The CMPTfeReturnAction action
  • • The CMPTfeReturnAction action is only available if the Terraform Connector Store Application is installed
    • Even if the CMPTfeReturnAction action is available, it may be desirable to use a custom action in order to keep the subflows that have no relationship to TFE (Terraform Enterprise) from referencing a TFE action
• Flow results should be populated as follows:
• • correlationid
  • • Set to the flowcorrelationid input parameter of the subflow
  • log
  • • An optional field only for logging purposes
  • response
  • • Result that is stored in the "Step Output" field of the "Cloud Orchestration Steps" table (sn_cmp_order_step_status)
    • This can be used to pass values between operations
    • Example use case
    • • A pre provisioning flow integrates with an IPAM solution to obtain an IP address
      • The flow populates the assigned IP in the response
      • At provision time a scripted Cloud Expression can be run (via Manage Attributes on the Catalog Item) to query the "Cloud Orchestration Steps" table to retrieve the assigned IP address
  • error
  • • Error details if the flow failed
    • If this field is set, Cloud Provisioning and Governance will mark the step as failed
• If a flow fails and returns an error then a retry option may be presented in the Cloud User Portal, however A RETRY WILL ALWAYS FAIL AND THE REQUEST MUST BE CANCELLED
• • Each subflow must have robust error handling to ensure that an error is returned only as a last resort with the expectation that the request will be cancelled
• Avoid using approvals in flows called by Cloud Provisioning and Governance where possible
• • Generally the Cloud Provisioning and Governance Policy engine is better suited for approvals

Creating an Example Subflow for Cloud Provisioning and Governance

As mentioned above, it is important to have robust error handling within the flow.  In this example, 2 subflows are created, a parent subflow and a child subflow.  The parent subflow will be launched by Cloud Provisioning and Governance.  The child subflow will execute some action (in this case checking for an open incident) and create a task if the action fails.  The task can be closed with the 3 out-of-box states (Complete, Skipped, Incomplete) which is then returned to the parent flow. 

• If the action was successful or the task is Closed Complete, the parent flow will return to Cloud Provisioning and Governance to continue processing
• If the task is Closed Skipped, the parent flow will rerun the child subflow to retry the action
• If the task is Closed Incomplete, the parent flow will return an error to Cloud Provisioning and Governance and the request will have to be cancelled

1. Open Flow Designer and create a new subflow
2. 1. Set "Name" to "CPG Subflow - Child Example" and "Run As" to "System User"
   2. 
2. Create a mandatory String input variable named "Request Item Sys ID"
3. 1. 
3. Create a mandatory String input variable using any appropriate name
4. 1. 
   2. NOTE : This will be used for example use only, in a real subflow you would add any number of appropriate input variables
4. Create a Choice output variable named "Result"
5. 1. Use "Reference existing choice list on a table" with the "Choice table" set to "Catalog Task" and "Choice field" set to "State"
   2. 
5. Add a "Look Up Records" action
6. 1. Set "Table" to "Incident" and "Conditions" to "Active" is "true" AND "Short description" contains <Input variable created in step #3>
   2. 
   3. NOTE : This will be used for example use only, in a real subflow you would add any number of real actions to fulfill the business need
6. Add an "If" action and name the condition "Success"
7. 1. Set the condition to "1 - Look Up Records.Count" is 0
   2. 
   3. NOTE : This is for example use only, in a real subflow you would configure a condition to indicate the action completed successfully
7. Inside of the "If" action from the previous step, create the following actions
8. 1. An "Assign Subflow Outputs" action
   2. 1. Set "Result" to "Closed Complete"
      2. Note : If the dropdown is empty after selecting the "Result" output variable, save the subflow
   2. An "End" action
   3. 
8. Add a "Create Task" action after (and outside of the "If" action) with the following fields
9. 1. "Assignment Group" = <any group>
   2. "Short Description" = <any short description>
   3. "Description" = <any description>
   4. 1. TIP : add a Note at the end of the Description to remind the fulfiller that Closed Complete will continue process, Closed Skipped will retry, and Closed Incomplete will abort the process
   4. "Request item" = <Request Item Sys ID Input variable created in step #2>
   5. "Parent" = <Request Item Sys ID Input variable created in step #2>
   6. Select the "Wait" option
   7. 
9. Add a "Assign Subflow Outputs" action
10. 1. Set "Result" to "5 - Create Task.Catalog Task Record.State"
    2. 
10. Save and Publish the subflow
11. Create a new subflow
12. 1. Set "Name" to "CPG Subflow - Parent Example" and "Run As" to "System User"
    2. 
12. Create a mandatory String input variable named "flowcorrelationid"
13. 1. 
13. Create a mandatory String input variable named "Request Item Sys ID"
14. 1. 
14. Create input variables to match those created in step #3
15. 1. 
15. Add a "Do the following until" action
16. 1. 
16. Inside of the "Do the following until" action create the following actions
17. 1. Add a "CPG Subflow - Child Example" subflow action
    2. 1. Set "Request Item Sys ID" to <Input variable created in step #13>
       2. Set other input variables as appropriate
       3. 
    2. Add an "If" action and name the condition "Subflow Cancelled"
    3. 1. Set the condition to "2 - Result" is "Closed Incomplete"
       2. 
    3. Inside of the "If" action from the previous step, create the following actions
    4. 1. A "CMPTfeReturnAction" action (Alternatively you could create a custom action as described in Best Practices)
       2. 1. Set "error" to "CPG Subflow - Child Example was Closed Incomplete"
          2. Set "log" to "CPG Subflow - Child Example was Closed Incomplete"
          3. Set "correlationid" to <Input variable created in step #12>
       2. An "End" action
       3. 
17. Update the "until" action
18. 1. Set "Condition" to "Subflow completed successfully"
    2. Set "Condition 1" to "2 - Result" is "Closed Complete"
    3. 
18. Add a "CMPTfeReturnAction" action (Alternatively you could create a custom action as described in Best Practices)
19. 1. Set "response" to "CPG Subflow - Child Example was Closed Complete"
    2. Set "log" to "CPG Subflow - Child Example was Closed Complete"
    3. Set "correlationid" to <Input variable created in step #12>
    4. 
19. Save and Publish the subflow

Testing the Subflow

1. Open Flow Designer and open the "CPG Subflow - Parent Example" subflow
2. Click "Test" and set the following values
3. 1. Set "flowcorrelationid" to "testing"
   2. Set "Request Item Sys ID" to <Sys ID of a real RITM>
   3. Set other input variables as required to ensure a successful result
   4. 
3. Click "Run Test"
4. Click on "Subflow has been executed. To view the subflow, click here."
5. Ensure no task was created and the subflow completed and it executed the CMPTfeReturnAction action without an error
6. 1. 
6. Repeat steps #1 - 4, using an input variables to ensure a failure result (use a different RITM Sys ID)
7. Ensure a task is created and closing the task "Closed Incomplete" completes the flow and executes the CMPTfeReturnAction action with an error
8. 1. 
   2. 
8. Repeat steps #1 - 4, using an input variables to ensure a failure result (use a different RITM Sys ID)
9. Ensure a task is created and closing the task "Closed Complete" completes the flow and executes the CMPTfeReturnAction action without an error
10. 1. 
    2. 
10. Repeat steps #1 - 4, using an input variables to ensure a failure result (use a different RITM Sys ID)
11. Ensure a task is created and close the task "Closed Skipped"
12. 1. 
12. Ensure a second task is created and resolve the issue causing the failure (in this example, close the incidents that contain the input keyword)
13. 1. 
13. Close the task "Closed Skipped" again and ensure the subflow has looped 3 times, it completes successfully, and it executes the CMPTfeReturnAction action without an error
14. 1. 

[Ram Devanathan1]

Super useful article - thank you so much @brian.quinn Appreciate the detailed description with steps and gotchas.

[Mark Radonic]

Thanks Brian for this, really helpful!

Can we consider this article as a way to implement a retry option on failed post provisioning or Day-2 operations?

Mark

[brian_quinn]

Yes.  This is one way to structure a flow to enable the ability for retries during post provisioning or Day 2 operations.  However, the option won't be in the Cloud User Portal, it will be handled more like Catalog Tasks that are created for non-cloud catalog items.