Configuring Service Catalog Requests

Once you connect EmpowerID to ServiceNow, your ServiceNow developers can configure ServiceNow to create EmpowerID objects via service catalog requests. This topic demonstrates how to configure ServiceNow to add an EmpowerID group service catalog request.

In ServiceNow, you need to create the following, all of which are covered in this topic.

• An OAuth provider that contains the information needed to connect with EmpowerID so that REST messages can be passed.

• Two new properties in the Request [sc_request] table to use in the Resume HTTP method of the REST message.

  • workflowinstanceid

  • workflowcorrelationid

• A REST message that calls the EmpowerID REST API with three POST HTTP methods.

  • Default POST: for starting the workflow on the ServiceNow side

  • Access Token: to get an access token for web API calls

  • Resume Workflow POST: for starting the workflow on the EmpowerID side

• A Business Rule on the Approval table that tracks EmpowerID group requests in the Approval table, and passes values to the REST message.

• A ServiceNow workflow to handle user requests from the service catalog.

• A service catalog request so users can request EmpowerID groups through ServiceNow.

Create an OAuth provider

The OAuth provider contains the information needed to connect with EmpowerID so that REST messages can be passed.

1. Log in to your ServiceNow instance, and in the navigation pane, search for Application Registry and select it.

2. Above the list of Application Registries, click the New button, and select Connect to a third party OAuth Provider.

3. Configure the new Application Registry with the following settings. (Skipped settings retain their default values.)

   • Name — EID

   • Client ID — The GUID from your EmpowerID OAuth application Client ID (Key)

   • Client Secret — The GUID from your EmpowerID OAuth application Client Secret

   • OAuth API Script — Click the search icon and select OAuthUtil.

   • Authorization URL — https://FQDN/oauth/v2/ui/authorize
     Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).

   • Token URL — https://FQDN/oauth/v2/token

   • Redirect URL — https://FQDN/WebIdPForms/oauth/v2

4.  Scroll to the bottom, and on the OAuth Entity Profiles tab, double-click the text Insert a new row and enter these values.

   • Name — EID default_profile

   • Is default — true

   • Grant type — Resource Owner Password Credentials

5. Click Submit to save the OAuth provider.

Add new columns to the Request table

Add two columns to the ServiceNow Request table to use in the Resume HTTP method parameters. The Resume method collects these values, along with the IsApproved value, via the HTTP query parameter script to pass to EmpowerID.

1. Log in to your ServiceNow instance, and in the navigation pane, search for Tables and select the one under System Definition.

2. Above the list of Tables, change the Go to drop-down from Name to Label, and search for Request.

3. Click the Request [sc_request] table.

4. On the Columns tab, click the New button to add a new Correlation ID column with the following settings. (Skipped settings can retain their default values.)

   • Type — String

   • Column label — Correlation ID

   • Column name — (autofills after a pause) u_correlation_id

   • Max length — 255

   • Active — selected

   • Display — selected

5. Click Submit to save the new column.

6. Back on the Columns tab, click the New button to add a new Workflow Instance ID column with the following settings. (Skipped settings can retain their default values.)

   • Type — String

   • Column label — Workflow Instance ID

   • Column name — (autofills after a pause) u_workflow_instance_id

   • Max length — 255

   • Active — selected

7. Click Submit to save the new column.

8. Back on the Request table, click Update to save the new columns to the Request table.

Create a REST message

The REST message is what passes information between ServiceNow and the EmpowerID REST API. It uses three methods to communicate via EmpowerID's anonymous endpoints. One method passes access tokens, another responds to group requests created in EmpowerID with approval or rejection, and the third notifies EmpowerID to create a group from a request in the ServiceNow services catalog.

1. In the navigation pane, search for REST Message and select it.

2. Above the list of REST Messages, click the New button.

3. Configure the new REST message with the following settings.

   • Name — EmpowerID API 
     Take note of the name you use, as it is used in the Creating an Approval Business Rule script below.

   • Accessible from — All application scopes

   • Endpoint — https://FQDN/oauth/v2/token 
     Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).

4. On the Authentication tab:

   • Change the Authentication type to OAuth 2.0.

   • For the OAuth profile, click the search icon and select the EID default_profile that you created earlier.

5. On the HTTP Request tab, add two HTTP Headers.

   1. In the list of HTTP Headers, double-click the text Insert a new row and enter these values.

      • Name — Content-Type

      • Value — application/json

   2. Insert another new row and enter these values.

      • Name — X-EmpowerID-API-Key

      • Value — your EmpowerID OAuth application API key

6. Click Submit to save the REST message. Back on the REST Messages list, click your newly created EmpowerID API REST message. A message at the top directs you to click the Get OAuth Token link to request a token.

7. Click the link, supply your EmpowerID admin username and password, and click Get OAuth Token.

8. Back on the EmpowerID API message, scroll to the bottom to see the HTTP Methods list.
   

   

9. Next to HTTP Methods, click the New button to create a new POST method. Create three in total, with the following settings. (Click Submit after each to return to the main REST Message page where you can add the next.)

Create an Approval business rule

The Approval table, where ServiceNow tracks EmpowerID group approval requests and their results, needs a business rule to pass values to the REST message.

1. Log in to your ServiceNow instance, and in the navigation pane, scroll down and expand System Definition, then find and select Business Rules. (You can also search for Business Rules, and select the one nested under System Definition.)

2. Above the list of Business Rules, click the New button, and add a new one named EmpowerID BR.

3. Configure the new business rule with the following settings.

   • Name — EmpowerID BR

   • Application — Global (default)

   • Table — Approval [sysapproval_approver]

   • Active — selected (default)

   • Advanced — selected (shows an advanced tab below, and adds fields)

4. On the When to run tab, set When to "after," and select the Update checkbox.

5. On the Advanced tab, paste this script to replace the default stub.
   

   (function executeRule(current, previous /*null when async*/) {
       
        // Code to create response for EmpowerID and update the Approval table
       try
           {
               var r = new sn_ws.RESTMessageV2("EmpowerID API", "Access Token");
               var response = r.execute();
               var responseBody = response.getBody();
               var parser = new JSONParser();
               var parsed = parser.parse(responseBody);
               var t = parsed.access_token;
               
               var regRecord = current.document_id.getRefRecord();
               if(regRecord.getValue('u_workflow_instance_id') != null)
               {
                   var r1 = new sn_ws.RESTMessageV2("EmpowerID API", "Resume");
                   r1.setStringParameterNoEscape("Token", t);
                   r1.setStringParameterNoEscape("WorkflowInstanceID", regRecord.getValue('u_workflow_instance_id'));
                   r1.setStringParameterNoEscape("CorrelationId", regRecord.getValue('u_correlation_id'));
                   r1.setStringParameterNoEscape("IsApproved", current.state);
                   var response1 = r1.execute();
                   var responseBody1 = response1.getBody();
                   var httpStatus1 = response1.getStatusCode();
               }
               else
               {
                   var req_item = new GlideRecord('sc_req_item');
                   req_item.addQuery('request', regRecord.sys_id);
                   req_item.query();
                   if(req_item.next())
                   {  		
                       var r2 = new sn_ws.RESTMessageV2("EmpowerID API", "Default POST");
                       r2.setStringParameterNoEscape("Token", t);
                       r2.setStringParameterNoEscape("Name", req_item.variables["group_name"].toString());
                       r2.setStringParameterNoEscape("Description", req_item.variables["group_description"].toString());
                       r2.setStringParameterNoEscape("Decision", current.state);
                       var response2= r2.execute();
                       var responseBody2= response2.getBody();
                       var httpStatus2 = response2.getStatusCode();
                   }
               }
           }
       catch(ex) 
           {
               var message = ex.getMessage();
           }     
   })(current, previous);                    

6. Click Submit to save the business rule.

Create a Workflow

This is where you set up the workflow to run when a user requests an EmpowerID group from the service catalog.

1. Log in to your ServiceNow instance, and in the navigation pane, search for Workflow Versions and select it.

2. Above the list of Workflow Versions, click the New button, and add a new workflow named EmpowerID WF.

3. Configure the new workflow version with the following settings.

   • Name — EmpowerID WF

   • Table — Request [sc_request]

4. On the Conditions tab, leave the default value of Run the workflow (or Run the workflow always) with no conditions.

5. On the Stages tab, leave the default value of Stage field (None) and change the Stage rendering value to Legacy.

6. Click Submit to save the workflow version. A new tab opens with the visual workflow designer.

7. From the Core tab on the right, drag workflow activities onto the designer to create a workflow like the one in this image using the settings below.
   

   

8. In the window that pops up when you drag each activity from a folder under Core Activities onto the workflow, use the settings in the list below the image.
   

   

   • Set Requested — From the Utilities folder, drag the Set Values activity onto the form and set it up with these values.

     • Name — Set Requested

     • Values --field — Approval

     • Values --value — Requested

     • Click Submit.

     • Click the dark yellow dot on the default Begin activity and drag it to your new activity to create a flow arrow.

   • Short Description starts with “EmpowerID” — From the Conditions folder, drag the If activity onto the form and set it up with these values.

     • Name — Short Description starts with 'EmpowerID'

     • Condition --choose field — Short description

     • Condition --choose operator — starts with

     • Condition --(string) — EmpowerID

     • Click Submit.

     • Click the dark yellow dot on the Set Requested activity and drag it to your new activity to create a flow arrow.

   • Send for approval to Sys Admin — From the Approvals folder, drag the Approval - User activity onto the form and set it up with these values.

     • Name — Send for approval to Sys Admin

     • Approvers --Users — System Administrator

     • Condition for approval — use default values

     • Schedule --Due date based on — A relative duration

     • Schedule --Relative duration — 2 business days by 4pm

     • Schedule --Schedule based on — A user specified schedule

     • Schedule --Schedule — 8-5 weekdays

     • Click Submit.

     • Click the dark yellow dot on the Short Description starts with 'EmpowerID' activity's Yes option and drag it to your new activity to create a flow arrow.

     • Click the dark yellow dot on the Short Description starts with 'EmpowerID' activity's No option and drag it to the End activity to create a flow arrow.

   • Approved — From the Approvals folder, drag the Approval Action activity onto the form and set it up with these values.

     • Name — Approved

     • Action — Mark task approved

     • Click Submit.

     • Click the dark yellow dot on the Send for approval to Sys Admin activity's Approved option and drag it to your new activity to create a flow arrow.

     • Click the dark yellow dot on the Approved activity and drag it to the End activity to create a flow arrow.

   • Rejected — From the Approvals folder, drag the Approval Action activity onto the form and set it up with these values.

     • Name — Rejected

     • Action — Mark task rejected

     • Click Submit.

     • Click the dark yellow dot on the Send for approval to Sys Admin activity's Approved option and drag it to your new activity to create a flow arrow.

     • Click the dark yellow dot on the Rejected activity and drag it to the End activity to create a flow arrow.

9. Click the Validate button (checkbox) above the workflow to ensure that it works.

10. Click the hamburger menu at the top left and select Publish to make your workflow available to all users.

11. If you need to edit the workflow, click the Show Workflow link at the bottom of the EmpowerID WF workflow version.

Create a service catalog request

The service catalog request provides a page in the ServiceNow service catalog where users can request a new EmpowerID group.

1. Log in to your ServiceNow instance, and in the navigation pane, search for Maintain Items and select it. (Or navigate to Service Catalog, then Catalog Definitions, and select it from there.)

2. Above the list of Catalog Items, click the New button, and add a new catalog item.

3. Configure the new catalog item with the following settings.

   • Name — EmpowerID Service Catalog Request

   • Catalogs — Service Catalog

   • Category — Services

   • Short Description — Request EmpowerID Group

   • Description — Create a group request. Once approved the group will be created in EmpowerID.

4. Click Submit, then open the EmpowerID Service Catalog Request from the list of catalog items. (Change the Go to value to Name to search for it.)

5. On the Variables tab at the bottom of the page, click New to add a variable with the following settings.

   • Question — Group Description

   • Name — group_description

   • Tooltip — Enter a description for the group.

6. Click Submit to save the variable.

7. Back on the Variables tab, click New to add a second variable with the following settings.

   • Question — Group Name

   • Name — group_name

   • Tooltip — Enter the name of the group.

8. Click Submit to save the second variable.

9. On the Approved By tab at the bottom of the page, click Edit to add an approver for EmpowerID group requests.

10. In the Collection search box, find and select System Administrator, and click the Add arrow to add it to the Approved By List.

11. Click Save to save the approver.