{"type":"doc","content":[{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"paragraph","content":[{"text":"ModelOp Center seamlessly integrates with existing ticketing systems, such as ServiceNow, to allow enterprises to orchestrate seamlessly change requests and incidents as part of the model life cycle.","type":"text"}]},{"type":"paragraph","content":[{"text":"Table of Contents","type":"text","marks":[{"type":"strong"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"ff163f53-b5a6-4517-be43-f933de0c7607"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"f792d477-3757-4489-be5d-2d1e543bac5c"}}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Introduction","type":"text"}]},{"type":"paragraph","content":[{"text":"ModelOp Center provides the ability for the Model Life Cycle to create and manage tickets within an existing ServiceNow system. The ticket types supported include change requests and incidents created and managed using the Table or Import Set APIs. This guide details the steps to enable integration.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"ServiceNow Integration Setup","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"This guide assumes ","type":"text"},{"text":"moc-builder","type":"text","marks":[{"type":"code"}]},{"text":" has been installed. Please request download instructions for ","type":"text"},{"text":"moc-builder","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.modelop.com/contact/"}}]},{"text":". Before configuring ","type":"text"},{"text":"moc-builder","type":"text","marks":[{"type":"code"}]},{"text":", the ServiceNow instance will need a service account created and configured. For an example of how to set up a service account see the instructions at ","type":"text"},{"text":"https://community.servicenow.com/community?id=community_blog&sys_id=b4fca2a5dbd0dbc01dcaf3231f961900","type":"text","marks":[{"type":"link","attrs":{"href":"https://community.servicenow.com/community?id=community_blog&sys_id=b4fca2a5dbd0dbc01dcaf3231f961900"}}]},{"text":". This guide assumes that the service account uses the email \"","type":"text"},{"text":"servicenow@modelop.com","type":"text","marks":[{"type":"link","attrs":{"href":"mailto:jira@modelop.com"}}]},{"text":"\". ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"moc-builder ServiceNow Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The integration requires the ModelOp Center Gateway url and the url of the ServiceNow instance to be integrated.","type":"text"}]},{"type":"paragraph","content":[{"text":"First, determine the external-ip of the Gateway. Set the Kubernetes context to the cluster and namespace that has ModelOp Center deployed. Run the following command: ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"kubectl get svc","type":"text"}]},{"type":"paragraph","content":[{"text":"The command will return an output like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"[johncarter@Johns-MacBook-Pro moc-builder (John@modelop-eks-test.us-east-2.eksctl.io:mocaasin)]$ kb get svc\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE\nengine-1 ClusterIP 10.100.72.22 8003/TCP 23h\nengine-2 ClusterIP 10.100.31.255 8003/TCP 23h\nengine-test ClusterIP 10.100.215.6 8003/TCP 23h\ngateway LoadBalancer 10.100.126.106 foo1.us-east-2.elb.amazonaws.com 8090:31166/TCP 23h\njupyter ClusterIP 10.100.242.107 8888/TCP 23h\nkafka ClusterIP 10.100.113.242 9092/TCP 23h\nminio ClusterIP 10.100.82.143 9000/TCP 23h\nmlc-manager LoadBalancer 10.100.145.82 foo3.us-east-2.elb.amazonaws.com 8085:31741/TCP 23h\nmodel-manager ClusterIP 10.100.205.30 8086/TCP,8088/TCP 23h\nmongodb ClusterIP 10.100.45.49 27017/TCP 23h\npostgres ClusterIP 10.100.77.22 5432/TCP 23h\nregistry ClusterIP 10.100.138.128 8761/TCP 23h\nreporting-service ClusterIP 10.100.38.87 8091/TCP 23h","type":"text"}]},{"type":"paragraph","content":[{"text":"The important value is the external-ip and port corresponding to the ModelOp Center Gateway. In this example, it’s ","type":"text"},{"text":"foo1.us-east-2.elb.amazonaws.com:8090","type":"text","marks":[{"type":"link","attrs":{"href":"http://foo1.us-east-2.elb.amazonaws.com:8090"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"NOTE: If the environment using ingresses instead of load balancers, run ","type":"text"},{"text":"kubectl get ing","type":"text","marks":[{"type":"code"}]},{"text":" and obtain the address corresponding to the ingress that points to gateway. Do not append the port number to the end of the address. That is only required if you are using the external IP from a service of type LoadBalancer.","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, open the ","type":"text"},{"text":"config.json","type":"text","marks":[{"type":"code"}]},{"text":" file within ","type":"text"},{"text":"moc-builder","type":"text","marks":[{"type":"code"}]},{"text":"’s config directory and navigate to the ","type":"text"},{"text":"mlc-manager","type":"text","marks":[{"type":"code"}]},{"text":" section. It will contain the following:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"mlc-manager\": {\n ...\n \"env\": {\n ...\n \"modelop.gateway-url\": \"http://gateway:8090\",\n ...\n \"mlc.servicenow-task-monitor.url\": \"http://servicenow\",\n ...\n },\n ...\n},","type":"text"}]},{"type":"paragraph","content":[{"text":"Change the value of the ","type":"text"},{"text":"modelop.gateway-url","type":"text","marks":[{"type":"code"}]},{"text":" env variable to be the location of gateway from above and change the value of the ","type":"text"},{"text":"mlc.servicenow-task-monitor.url","type":"text","marks":[{"type":"code"}]},{"text":" to be the location of the ServiceNow instance. In this example, the ServiceNow instance is located at \"","type":"text"},{"text":"https://instance.servicenow.com\"","type":"text","marks":[{"type":"link","attrs":{"href":"https://foo.atlassian.net"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is the example ","type":"text"},{"text":"config.json","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"mlc-manager\": {\n ...\n \"env\": {\n ...\n \"modelop.gateway-url\": \"http://foo1.us-east-2.elb.amazonaws.com:8090\",\n ...\n \"mlc.servicenow-task-monitor.url\": \"https://instance.servicenow.com\",\n ...\n },\n ...\n},","type":"text"}]},{"type":"paragraph","content":[{"text":"Go ahead and save the config file and open up the file located in ","type":"text"},{"text":"moc-builder","type":"text","marks":[{"type":"code"}]},{"text":" at ","type":"text"},{"text":"data/secrets.json","type":"text","marks":[{"type":"code"}]},{"text":". Here is how the file looks:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n ...\n \"SERVICENOW_USERNAME\": \"demo\",\n \"SERVICENOW_PASSWORD\": \"modelop\",\n ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Change the ","type":"text"},{"text":"SERVICENOW_USERNAME","type":"text","marks":[{"type":"code"}]},{"text":" value to be the email associated with the service account and the ","type":"text"},{"text":"SERVICENOW_PASSWORD","type":"text","marks":[{"type":"code"}]},{"text":" to be the service account password.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is the example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n ...\n \"SERVICENOW_USERNAME\": \"servicenow@modelop.com\",\n \"SERVICENOW_PASSWORD\": \"password goes here\",\n ...\n}","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Security","type":"text"}]},{"type":"paragraph","content":[{"text":"As mentioned in ","type":"text"},{"text":"Prerequisites","type":"text","marks":[{"type":"link","attrs":{"href":"#Prerequisites"}}]},{"text":" we recommend using a service account for the ServiceNow integration. Limit the access rights of the service account to just those needed for the integration and only use the service account for the integration. The security advantages to using a service account are explained ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://community.servicenow.com/community?id=community_blog&sys_id=b4fca2a5dbd0dbc01dcaf3231f961900"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The integration uses Basic Authentication to authenticate REST calls to ServiceNow. The credentials can be set up using Kubernetes secrets, as in the configuration example above, or using ","type":"text"},{"text":"Vault","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DV21/pages/1774485557/Integrate+with+Vault"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"ServiceNow Ticket Customization","type":"text"}]},{"type":"paragraph","content":[{"text":"The integration provides a variety of parameters to allow customization of ServiceNow ticket creation and lifecycle management within the Model Life Cycle. Some of these parameters are discussed in more detail below.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Ticket Creation","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_API","type":"text","marks":[{"type":"code"}]},{"text":" - The API to use when creating tickets (table or import). The integration supports both the Table API and the Import Set API for ticket creation.","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_TABLE_NAME","type":"text","marks":[{"type":"code"}]},{"text":" - The table to create new tickets in. This is the path parameter of the API being used. This is usually change_request, incident, or the name of an Import Set.","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_CUSTOM_FIELDS","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"- A JSON string containing any custom fields to send with the creation request. By default the implementation will provide data for a few fields and this parameter allows setting as many fields as needed. If a ","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"u_uuid","type":"text","marks":[{"type":"code"}]},{"text":" field is required per request, including retries, then set the field to empty string and the integration will generate a random UUID to use for each request.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Ticket Updates","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_UPDATES","type":"text","marks":[{"type":"code"}]},{"text":" - A JSON string specifying additional updates to make to the ticket after creation. Some workflows require additional automated updates to the ticket after creation. This field includes the required information to make those updates. UUID generation works here the same as for ","type":"text"},{"text":"SERVICENOW_CUSTOM_FIELDS","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text","marks":[{"type":"em"}]},{"text":" If a field needs to use the value from the current state of the ticket include that field in the payload and set the value to empty string. The integration will replace the value with the ","type":"text"},{"text":"value","type":"text","marks":[{"type":"code"}]},{"text":" of the field in the ticket. The structure of the JSON is shown below:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"[\n {\n \"serviceNowApi\" : \"(table|import)\",\n \"serviceNowTableName\" : \"tableName\",\n \"serviceNowCustomFields\" : {\n \"field1\":\"value1\",\n \"replacement\": \"\",\n ...\n }\n ...\n]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Ticket Lifecycle","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_EXIT_STATUS_FIELD","type":"text","marks":[{"type":"code"}]},{"text":" - The field on the ticket to watch for an exit state. The Model Life Cycle waits until this field reaches a desired ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":". By default the integration watches the ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code"}]},{"text":" field. The ","type":"text"},{"text":"display_value","type":"text","marks":[{"type":"code"}]},{"text":" of the field is watched.","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" - A string listing out the exit statuses for the ticket. When the ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS_FIELD","type":"text","marks":[{"type":"code"}]},{"text":" reaches one of the exit statuses in this parameter the Model Life Cycle will stop watching the ticket and proceed.","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_EXIT_CONDITIONS","type":"text","marks":[{"type":"code"}]},{"text":" - A string listing out a list of statuses and exit conditions that must be met for the status to be realized. Some workflows require considering multiple fields to determine if the ticket has met its exit status. This field uses a CSV-like format to list out conditions. Specifically,","type":"text"}]},{"type":"codeBlock","content":[{"text":"Status1,ConditionType1,Condition1\nStatus2,ConditionType2,Condition2\n…","type":"text"}]},{"type":"paragraph","content":[{"text":"where commas are used as a separator. Commas are permitted in the condition. A new line indicates the beginning of a new condition. Both juel and spel conditions are supported.","type":"text"}]},{"type":"paragraph","content":[{"text":"As an example, a workflow may require watching the ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code"}]},{"text":" field to reach ","type":"text"},{"text":"canceled","type":"text","marks":[{"type":"code"}]},{"text":" or for the ","type":"text"},{"text":"approval","type":"text","marks":[{"type":"code"}]},{"text":" field to reach ","type":"text"},{"text":"approved","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"rejected","type":"text","marks":[{"type":"code"}]},{"text":". The conditions for such a workflow could look like the following.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"Canceled,juel,\\${ticket.state.display_value.equalsIgnoreCase('canceled')}\nRejected,juel,\\${ticket.approval.display_value.equalsIgnoreCase('rejected')}\nApproved,juel,\\${ticket.approval.display_value.equalsIgnoreCase('approved')}","type":"text"}]},{"type":"paragraph","content":[{"text":"The conditions are evaluated in the order they are listed. The ","type":"text"},{"text":"ticket","type":"text","marks":[{"type":"code"}]},{"text":" variable is provided for expression evaluation by the integration and represents the current state of the ticket. The ","type":"text"},{"text":"\\$","type":"text","marks":[{"type":"code"}]},{"text":" is escaped in the example above so that Camunda itself will not attempt to evaluate the juel conditions. When a condition is satisfied the ","type":"text"},{"text":"TICKET_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" variable will be set to the matching status for further use in the Model Life Cycle.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only one of ","type":"text"},{"text":"SERVICENOW_EXIT_CONDITIONS","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" will be used when determining if a ticket has reached exit status with the following priority order:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Local ","type":"text"},{"text":"SERVICENOW_EXIT_CONDITIONS","type":"text","marks":[{"type":"code"}]},{"text":" variable","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Local ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" variable","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SERVICENOW_EXIT_CONDITIONS","type":"text","marks":[{"type":"code"}]},{"text":" variable","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" variable","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In cases 2 and 4 ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" can be set to null to indicate that there should be no wait after creation and update. If ","type":"text"},{"text":"SERVICENOW_EXIT_CONDITIONS","type":"text","marks":[{"type":"code"}]},{"text":" is used then ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS_FIELD","type":"text","marks":[{"type":"code"}]},{"text":" has no affect.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Raising/Managing Change Requests","type":"text"}]},{"type":"paragraph","content":[{"text":"To use a change request within a Model Life Cycle a notification must be created and stored and then the ticket created and the lifecycle managed. We provide examples of how to use the different notifications in the mlc-building-blocks. A simple example is shown below. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start"},"content":[{"type":"media","attrs":{"width":657,"id":"f637bf0a-dfd8-4e06-be30-8d2d248c856c","collection":"contentId-1152417883","type":"file","height":141}}]},{"type":"paragraph","content":[{"text":"The Simple Notification requires the following parameters.","type":"text"}]},{"type":"paragraph","content":[{"text":"NOTIFICATION_MESSAGE","type":"text","marks":[{"type":"code"}]},{"text":" - A message to include in the notification. This message will appear on the ModelOp dashboard. It will also appear as part of the ","type":"text"},{"text":"short_description","type":"text","marks":[{"type":"code"}]},{"text":" and in some cases ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code"}]},{"text":" of the ServiceNow ticket unless those fields are overridden using ","type":"text"},{"text":"SERVICENOW_CUSTOM_FIELDS","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"NOTIFICATION_SEVERITY","type":"text","marks":[{"type":"code"}]},{"text":" - The severity of the notification (INFO, WARN, ERROR, etc.). This will be reflected in the ModelOp dashboard notification.","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_API","type":"text","marks":[{"type":"code"}]},{"text":" - The API to use for creating the ServiceNow ticket (table or import).","type":"text"}]},{"type":"paragraph","content":[{"text":"SERVICENOW_TABLE_NAME","type":"text","marks":[{"type":"code"}]},{"text":" - The ServiceNow table to create the ticket in. If using the Table API this will be change_request. If using the Import Set API this will be the name of the import set.","type":"text"}]},{"type":"paragraph","content":[{"text":"Supplying these parameters correctly will result in a dashboard notification and a ServiceNow ticket being created. After ticket creation, however, the Model Life Cycle will continue on and not wait for any specific status of the ticket. In some cases this is desirable but often waiting for a specific status is the desired behavior. The ","type":"text"},{"text":"SERVICENOW_EXIT_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" variable can be used to set the the status to wait for. For example, if set to “closed,canceled” then the Model Life Cycle will wait until the ticket’s ","type":"text"},{"text":"state.display_value","type":"text","marks":[{"type":"code"}]},{"text":" has reached either the closed or canceled status before continuing. The final status will be set in the ","type":"text"},{"text":"TICKET_STATUS","type":"text","marks":[{"type":"code"}]},{"text":" variable which the Model Life Cycle can use to determine different paths of execution. See ","type":"text"},{"text":"ServiceNow Ticket Customization","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":" for more parameters for customizing ticket creation, updates, and lifecycle management.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Raising/Managing Incidents","type":"text"}]},{"type":"paragraph","content":[{"text":"Raising and managing an incident is nearly identical to ","type":"text"},{"text":"Raising/Managing Change Requests","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":". Ensure that ","type":"text"},{"text":"SERVICENOW_TABLE_NAME","type":"text","marks":[{"type":"code"}]},{"text":" is set to either incident (if using the Table API) or the name of the appropriate import set. That’s it! An incident will be created instead of a change request. Update any other ","type":"text"},{"text":"parameters","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":" as needed to manage creation, updates, and lifecycle.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"MLC Example Usages","type":"text"}]},{"type":"paragraph","content":[{"text":"A common usage pattern is to create the ServiceNow ticket, update the deployable model with the URL of the ticket in the custom metadata, and then wait for the exit conditions/status. This allows the URL of the ticket to be shown on the snapshot page. An example from mlc-building-blocks is shown below.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start"},"content":[{"type":"media","attrs":{"width":533,"id":"5e295035-57b1-4071-b2d7-63bba119236a","collection":"contentId-1152417883","type":"file","height":481}}]},{"type":"paragraph","content":[{"text":"Using this sub-process will produce a dashboard notification and custom metadata update similar to those shown below.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":50.0},"content":[{"type":"media","attrs":{"width":773,"id":"1fe80c22-23c9-48be-a400-610a65860faf","collection":"contentId-1152417883","type":"file","height":143}}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":50.0},"content":[{"type":"media","attrs":{"width":767,"id":"ff3028bc-dced-4a43-9e8e-fa5ab223306b","collection":"contentId-1152417883","type":"file","height":132}}]},{"type":"paragraph"},{"type":"paragraph"},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Related Articles","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph"}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"}]}]}],"version":1}