Identity Manager 8.1 - Administration Guide for Connecting to ServiceNow

Use Case Scenario with ServiceNow as a One-Stop Shop and Configuration

Use Case Scenario with ServiceNow as a One-Stop Shop and Configuration

This functional requirement is about the integration of One Identity Manager IT shop into the ServiceNow portal. This implementation is achieved by combining the External Content View of a content item in ServiceNow and Deep linking feature of the One Identity Manager Web portal page.

The below mentioned One Identity Manager web portal’s authentication modules are explained as use case scenarios:

  • Employee (Role based)

  • SSO OAuth 2.0

Before configuring the One Identity Manager web portal, the ServiceNow portal must be configured to display the external content item.

ServiceNow portal configuration

The procedure to configure the ServiceNow portal is detailed below:

  1. Login to the ServiceNow instance. Create a new category in Service Catalog section by navigating to Service Catalog | Catalog Definitions | Maintain Categories | New. Assign a catalog to the category.

    Figure 3: Maintain Categories

  2. Create a new content Item by navigating to Service Catalog | Catalog Definitions | Content Items | New. Select the Content Type to External Content. In the URL Tab, paste the deep links to One Identity Manager. An example url is given below. The context ID changes based on the page which is to be shown. These pages can be found in the Web Designer.
    • Syntax: https://<WebPortalServer>/IdentityManager/page.axd?ContextID=<PageLink>

    • Example: https://webportalserver.com/IdentityManager/page.axd?ContextID=VI_ITShop_ProductSelection
  1. Assign a catalog, category, icon to the newly created content item as explained in the below image.

    Figure 4: Assigning Catalog

  2. The newly created category should be added to the Service Catalog page. Navigate to Self Service | Service Catalog. Click the + button on the upper right corner of the screen. Search for the newly created category and add it on to the screen.

    Figure 5: Service Catalog

One Identity Manager Web Portal Configuration: Employee Based (Role Based) Authentication Module

  1. Open WebDesigner.ConfigFileEditor.
  2. Select the web.config for the One Identity Manager web portal. Click Open. The Web Designer Configuration Editor page opens from where the Authentication module can be selected.

    Figure 6: Web Designer Configuration Editor

Behavior of One Identity Manager in ServiceNow with Employee authentication module

  • When the link is clicked for the first time in a ServiceNow portal, an authorization page to the One Identity Manager web portal is shown for the user credentials of One Identity Manager to be entered.

    Figure 7: One Identity Manager

  • Post log in

    Figure 8: Logged In

  • Logging on to the ServiceNow portal in the same browser in a different tab with a different ServiceNow user. The login in still uses the last logged on user to login to the ServiceNow portal still uses.

    Figure 9: Last Logged On

 

  • When the browser is closed and a new instance of the browser is opened, the ServiceNow instance’s One Identity Manager item Request Items require credentials, to log into One Identity Manager again.

One Identity Manager Web Portal Configuration: OAuth 2.0 / OpenID Connect (role based) – SSO Authentication module

This method requires the One Identity Manager to be configured within the STS SSO module. Please refer to One Identity Manager documentation while configuring the STS SSO module.

  1. Open WebDesigner.ConfigFileEditor.

  2. Select the web.config for the One Identity Manager web portal. Click Open. The Web Designer Configuration Editor page opens from where the Authentication module can be selected.

    Figure 10: Web Designer Configuration Editor

Behavior of One Identity Manager in ServiceNow with OAuth 2.0 SSO configured

  • When the link is clicked for the first time in a service now portal, an authorization page to the One Identity Manager RSTS portal (SSO) is shown where the domain user credentials have to be entered.

    Figure 11: One Identity Manager

  • Post Logging In

    Figure 12: After Logging In

  • Product Listing

    Figure 13: Product Listing

  • Logging on to the ServiceNow portal in the same browser in a different tab, with a different ServiceNow user. The log on to the ServiceNow portal still uses the last logged on user.

    Figure 14: Service Item Request

  • When the browser is closed and a new instance of the browser is opened, the ServiceNow instance’s One Identity Manager item Request Items opens the One Identity Manager IT shop with the last logged on One Identity Manager domain user.

    Figure 15: One Identity Manager Request

Logging out from ServiceNow

When a user logs out of the ServiceNow portal, the process to log off from the One Identity Manager Web session starts. ServiceNow allows customization of the log off from the portal, which can be used to browse the One Identity Manager deep link which clears the authentication session.

One Identity Manager 8.X has no log out URL available for clearing the SSO session, which needs to be implemented in One Identity Manager OAuthenticator module to solve this use-case. Feature ID aimed at solving the impediment is 771671. A workaround for the log out issue is to log off the One Identity Manager session, before logging out of the ServiceNow portal.

Customization of ServiceNow Module

The customization of ServiceNow module is described in the section below.

Creating ServiceNow Ticket – Adding more attributes to the ticket creation

Creating ServiceNow Ticket – Adding more attributes to the ticket creation

The ServiceNow component CreateTicket is responsible for creation of tickets. The procedure to create tickets is listed below:

  1. In the One Identity Manager Designer, navigate to Process Orchestration | Process Components | SCNComponent | CreateTicket.

  2. Create a new parameter for the CreateTicket task. This parameter should be in line with a ServiceNow parameter.

    1. Enter a name in the appropriate field. The Name field must be in line with the resolved_by attribute.
    2. Enter the value template in the appropriate field. The Value template can be configured as required with the syntax: Value = <Value to be configured>

A process step with the CreateTicket task sends the configured values to ServiceNow for creating a ticket. The process chain Create Service Now Ticket uses this process step for creating a ticket.

Manipulating the response from ServiceNow

The process step with GetTicketStatus task gets the status of a ticket.

The process chain SCN_Create ServiceNow Ticket is responsible for creating a ticket in ServiceNow and, updating the field ServiceNowSystemID of the PersonWantsOrg table. This field is later used in the SCN_Check_status_of_the_ServiceNow_ticket process chain which is called over time. This process chain contains a process step using the GetTicketStatus task which uses the ServiceNowSystemID as a reference to the ServiceNow and returns the status in the field SNOWResponse.

SNOWResponse value is a JSON response which is then parsed to get any desired field of the ServiceNow response schema. These fields can later be leveraged to change the status of the associated PersonWantsOrg entry accordingly.

This SNOWResponse value is used in the script SCN_UpdatingOneIMTicketStatus. This is first parsed to a NewtonSoft JObject type and then values are taken out using the SelectToken function. Further explanation is given below.

The response value script is represented below:

#If Not SCRIPTDEBUGGER
References Newtonsoft.Json.dll
#End If
'This script is used for updating the status from the ServiceNow ticket to the corresponding PersonWantsOrg entry in OneIM.
'Dieses Skript wird zum Aktualisieren des Status vom ServiceNow-Ticket zum entsprechenden PersonWantsOrg-Eintrag in OneIM verwendet.
Public Overridable Function SCN_UpdatingOneIMTicketStatus( ByVal statusResultsData As String , ByVal UID_PWO As String) As Boolean
Dim PWO As ISingleDbObject = Connection.CreateSingle("PersonWantsOrg", UID_PWO)
 
Dim snowResponse As Newtonsoft.Json.Linq.JObject = Nothing
Try
snowResponse = Newtonsoft.Json.Linq.JObject.Parse(statusResultsData)
'We can retrieve any value from the ServiceNow Response JSON.
'In this script, we are getting the values for "sys_id", "number", "state", etc.
'A detailed sample of a JSON response can be found in the OneIM Administration Guide.
 
'Wir können jeden Wert aus dem ServiceNow-Antwort-JSON abrufen.
'In diesem Skript erhalten wir die Werte für "sys_id", "number", "state" usw.
'Ein detailliertes Beispiel einer JSON-Antwort finden Sie im OneIM-Administrationshandbuch.
 
'Syntax to get a value from the json : snowResponse.SelectToken("<variable name>").ToString()
'Syntax, um einen Wert aus dem json: snowResponse.SelectToken ("<Variablenname>") . ToString ()
 
'Example : snowResponse.SelectToken("sys_id").ToString()
'Beispiel: snowResponse.SelectToken ("sys_id"). ToString ()
 
'Any internal fields or nested fields can be queried in the format:
'Alle internen Felder oder verschachtelten Felder können im folgenden Format abgefragt werden:
 
'snowResponse.SelectToken("<parent1 variable name>").SelectToken("<Parent2 Or internal field name>")....ToString()
 
'Example:" snowResponse.SelectToken("resolved_by").SelectToken("link").ToString()
'Beispiel: "snowResponse.SelectToken (" resolved_by "). SelectToken (" link "). ToString ()
 
Dim sysID As String = snowResponse.SelectToken("sys_id").ToString()
Dim incnumber As String = snowResponse.SelectToken("number").ToString()
Dim status As String = snowResponse.SelectToken("state").ToString()
Dim ownerID As String = snowResponse.SelectToken("sys_updated_by").ToString()
Dim close_code As String = snowResponse.SelectToken("close_code").ToString()
Dim close_notes As String = snowResponse.SelectToken("close_notes").ToString()
Dim resolved_at As String = snowResponse.SelectToken("resolved_at").ToString()
 
'The value for the status variable should be modified to the value as configured at the ServiceNow End
'Der Wert für die Statusvariable sollte auf den Wert geändert werden, der im ServiceNow-Ende konfiguriert wurde
 
If status = "6" Then
'On the basis of the state, we can make the necessary decision on the PersonWantsOrg entry.
'Auf der Grundlage des Staates können wir die notwendige Entscheidung über den Eintrag PersonWantsOrg treffen.
 
'Deutsche Übersetzung des folgenden Anrufs
'Beispiel: PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket 123 wurde erfolgreich vom Benutzer admin geschlossen")
 
PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket#" + incnumber + " was closed successfully by " + ownerID + " " + sysID +"")
PWO.PutValue("SNOWExt",True)
 
PWO.Save()
 
End If
 
Return True
Catch ex As Exception
Return False
End Try
End Function
 

Based on the configuration of values in the ServiceNow end, the value of the order state can be changed. For instance,

If status = "6" Then
'On the basis of the state, we can make the necessary decision on the PersonWantsOrg entry.
'Auf der Grundlage des Staates können wir die notwendige Entscheidung über den Eintrag PersonWantsOrg treffen.
 
'Deutsche Übersetzung des folgenden Anrufs
'Beispiel: PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket 123 wurde erfolgreich vom Benutzer admin geschlossen")
 
PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket#" + incnumber + " was closed successfully by " + ownerID + " " + sysID +"")
PWO.PutValue("SNOWExt",True)
 
PWO.Save()
 
End If
 

Here, a ServiceNow instance has the state “6” configured as close and assigned in ServiceNow. Hence, the custom call PWO.Custom.CallMethod(“MakeDecision”,””, True,”Message”) is set to true.

If a request is denied from the service now, then the custom call changes to PWO.Custom.CallMethod(“MakeDecision”,””, True,”Message”) is set to false.

Please ensure that the statement PWO.PutValue(“SNOWExt”,True) is present, after any decision making step as its value is used in other process chains.

The SnowResponse can be used to retrieve any field of the ServiceNow response. These retrieved values can be used to set the variables of a ticket. For example,

If status = "6" Then
'On the basis of the state, we can make the necessary decision on the PersonWantsOrg entry.
'Auf der Grundlage des Staates können wir die notwendige Entscheidung über den Eintrag PersonWantsOrg treffen.
 
'Deutsche Übersetzung des folgenden Anrufs
'Beispiel: PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket 123 wurde erfolgreich vom Benutzer admin geschlossen")
 
PWO.Custom.CallMethod("MakeDecision", "", True, "Ticket#" + incnumber + " was closed successfully by " + ownerID + " " + sysID +"")
PWO.PutValue("SNOWExt",True)
 
PWO.Save()
 
End If
 

In this script, the message portion of the custom call is configurable. We have configured the message to display some text and values of the field “sys_udpated_by” and “sys_id”. These values are retrieved before this If block as shown below:

Dim sysID As String = snowResponse.SelectToken("sys_id").ToString()

Dim ownerID As String = snowResponse.SelectToken("sys_updated_by").ToString()

Similarly more values can be retrieved with the syntax,

  • Dim testPropName As type = snowResponse.SelectToken(“ServiceNow field name”).ToString()

For internal child fields,

  • Dim testPropName As type = snowResponse.SelectToken(“ServiceNow parent name”).SelectToken(child1)….ToString()

These retrieved values can also be used to set some field of PersonWantsOrg entry like ReasonHead for instance.

General Syntax: PWO.PutValue(“<PersonWantsOrg field name>”,testPropName)

Example:

  • Dim closenotes As String = snowResponse.SelectToken(“close_notes”)
  • PWO.PutValue(“ReasonHead”, closenotes )

Please note that the PWO.PutValue is only applicable after the initialization in the script.

NOTE: Script SCN_UpdatingOneIMTicketStatus cannot be modified directly. If further customizations are required on this script, new custom scripts must be created by copying this script’s content and changes can be done on the new script. Please change the function’s name as well and use the same custom script name in the process step as well. The process chain referencing this script is SCN_Check status of the ServiceNow ticket. The internal process step where the ScriptName should be modified is “Updating the One IM with status of resolved tickets”.

Constructing the Request for updating One Identity Manager status to ServiceNow ticket

The process chain SCN_Update_1IM_ticket_status_to_ServiceNow is responsible for constructing the response for ServiceNow update. This response is then sent to the ServiceNow end, through the process task UpdateServiceNowStatus. This task has a parameter RequestBody that takes the value from the preceding step, in the process chain which calls the script SCN_GetOrderValueStatus which constructs the response. Below is the script with an example on how the script can be modified.

#If Not SCRIPTDEBUGGER
References Newtonsoft.Json.dll
#End If
'This script gets the OrderState value status from the PersonWantsOrg table with reference of the UID_PWO sent from the calling step
'Dieses Skript ruft den OrderState-Wertstatus aus der Tabelle "PersonWantsOrg" mit der Referenz der UID_PWO ab, die vom aufrufenden Schritt gesendet wurde
'On the basis of the OrderState value the necessary response is generated as explained in this script further on
'Auf der Grundlage des OrderState-Werts wird die erforderliche Antwort generiert, wie in diesem Skript weiter erläutert
Public Overridable Function SCN_GetOrderValueStatus(ByVal UID_PWO As String) As String
 
Dim PWO As ISingleDbObject = Connection.CreateSingle("PersonWantsOrg", UID_PWO)
Dim responseBodyStr As String = ""
Dim orderstate As String = PWO.GetValue("OrderState").String
Dim requestBody As Newtonsoft.Json.Linq.JObject = New Newtonsoft.Json.Linq.JObject()
'The Request JSON  for the response will have to constructed based on the value of the OrderState in OneIM and
'the corresponding field values that are configured on the ServiceNow end.
'Der Anforderungs-JSON für die Antwort muss basierend auf dem Wert des OrderState in OneIM und
'den entsprechenden Feldwerten erstellt werden, die auf dem ServiceNow-Ende konfiguriert sind.
'To add any more fiels to the request JSON, add it in the format, requestBody.Add("<fieldname>","<Value>")
'Um der Anfrage JSON weitere Felder hinzuzufügen, fügen Sie sie im Format requestBody.Add ("<Feldname>", "<Wert>") hinzu.
'Example: requestBody.Add("close_code","Closed/Resolved by Caller")
'Beispiel: requestBody.Add ("close_code", "Closed / Resolved by Caller")
Select orderState
Case "Assigned"
requestBody.Add("close_code","Closed/Resolved by Caller")
requestBody.Add("state","7")
requestBody.Add("close_notes",PWO.GetValue("ReasonHead").String)
responseBodyStr = requestBody.ToString()
Case "Granted"
requestBody.Add("state","2")
responseBodyStr = requestBody.ToString()
Case "Dismissed"
requestBody.Add("close_code","Closed/Resolved by Caller")
requestBody.Add("state","7")
requestBody.Add("close_notes",PWO.GetValue("ReasonHead").String)
responseBodyStr = requestBody.ToString()
Case "OrderProduct"
requestBody.Add("state","2")
responseBodyStr = requestBody.ToString()
Case "Aborted"
requestBody.Add("close_code","Closed/Resolved by Caller")
requestBody.Add("state","7")
responseBodyStr = requestBody.ToString()
Case Else
responseBodyStr = ""
End Select
Return responseBodyStr
End Function
 

In the script, the Cases sections contain the responses for various OrderState values of the PersonWantsOrg entries.

For instance:

 

Case "Assigned"
requestBody.Add("close_code","Closed/Resolved by Caller")
requestBody.Add("state","7")
requestBody.Add("close_notes",PWO.GetValue("ReasonHead").String)
responseBodyStr = requestBody.ToString()
 

Here, the variable requestBody contains the request that is to be sent to ServiceNow. In this case, we are adding the ServiceNow fields close_code, state, close_notes. These fields are mandatory for any ticket to be closed on ServiceNow for resolution. More fields can be added with the requestBody before the statement responseBodyStr = requestBody.ToString().

  • Syntax to add more fields: requestBody.Add(“<ServiceNow field name>”,”<Value>”)
  • Example: requestBody.Add(“resoved_by”,$DisplayPersonHead$)

Here $DisplayPersonHead$ is the value of the person taking a decision as configured in the approval work flow.

NOTE: Script SCN_GetOrderValueStatus cannot be modified directly. If further customizations are required on this script, new custom scripts must be created by copying this script’s content and then changes can be done on the new script. Please change the function’s name and use the same custom script name in the process step. The process chain referencing this script is SCN_Update_1IM_ticket_status_to_ServiceNow. The internal process step where the ScriptName should be modified is Script to process the OrderValue property of One Identity Manager.

Troubleshooting

Issues related to the working of this module ranges from server related issues to job server latencies. Some of the issues that could affect the working of this module are mentioned below:

  • Network issues connecting the ServiceNow instance with the Job Server handling ServiceNow tasks

  • ServiceNow connectivity issues related to the instance’s unavailability

  • ServiceNow connectivity issues due to incorrect credentials

  • ServiceNow connectivity issues due to controlled access over ServiceNow

  • Job Server latency or downtime which would affect the ticket creation for the PersonWantsOrg requests

The triggering of ServiceNow process chains depend on the One Identity Manager database changes.

NOTE:If activities of ServiceNow are not working as expected, job server logs must be observed and validated for errors.
Related Documents