EmpowerID Orchestration Pack for ServiceNow

The EmpowerID Orchestration Pack for ServiceNow provides ServiceNow process designers with workflow activities, web services, and example workflows to embed EmpowerID capabilities within their ServiceNow business processes. EmpowerID includes a job that synchronizes and maintains an up-to-date list of requestable groups and roles from the EmpowerID Identity Warehouse to custom tables in your ServiceNow tenants. Using the embedded EmpowerID workflow activities in your ServiceNow workflows, users can request access to entitlements in any EmpowerID-connected system from the familiar ServiceNow Service Catalog. In addition, the Orchestration Pack provides the ability to integrate an AI-powered chat bot virtual assistant, the EmpowerID Bot, into ServiceNow. With the bot, users can perform secure self-service, such as resetting their passwords, at any time within the ServiceNow portal.

The orchestration pack allows you to incorporate the power of EmpowerID’s Compliant Access Delivery platform into your business processes, enhancing those processes with the end-to-end security of EmpowerID. This ensures that only users with the necessary access level can initiate any ServiceNow business process that uses the activities within the pack, routing those processes for further approval where necessary. Upon approval, immediate fulfillment occurs in ServiceNow and any other target systems. EmpowerID maintains an audit log of these processes that is permanently stored in the Identity Warehouse with the details of “who, what, where and when.” This gives you visibility over any action occurring in ServiceNow that uses the workflow activities in the orchestration pack.

Example Workflows

Example workflows included in the orchestration pack include those listed below. While these example workflows can be used in production without modification, they are intended to be leveraged by ServiceNow process designers in existing and future workflows. For an example of using an EmpowerID workflow as a subflow for another workflow, see Extending ServiceNow with the Orchestration Pack.

EID – New Hire

This workflow is built to create a new user using the EmpowerID APIs. When a new hire request is submitted, the workflow invokes the Admin Approval activity. Currently, this is a placeholder activity that sends an approval request to the system administrator to demonstrate approvals. Once approved by system admin (If rejected, the request is marked as “closed incomplete” and the workflow ends.), the workflow proceeds to execute the Run Script block. This block receives the input parameters from the submitted request form, and triggers the API call to EmpowerID using these details. The details about the API call can be found in the Integrations sections of this document. Once the call is made, the request is marked as “closed complete” and the workflow ends.

EID – Add User to Group

This workflow is built to add user to a group within EmpowerID. When a request is submitted using this workflow it first runs a script block named “Subflow variable mapping”. This is an important step in case we want to use the EmpowerID workflow as a subflow in an existing customer workflow. The second step is the Approval activity, which is currently approved by the system administrator. Once approved (if rejected, the workflow sets the state of the request as “closed inomplete” and ends here), the workflow continues to the third step, which is where the actual API call to EmpowerID is made with all required parameters. Please refer the integrations section of this document to know the details of the API. After a successful call, the workflow marks the state of the RITM as “Closed Complete” and ends.

EID – Request Management Role

This workflow is build to associate a management role to a user within EmpowerID for a specified duration of time. At the very beginning, the workflow runs a script block which deals with variable mapping in case when this workflow is being used as a subflow. The second step is the approval activity, which is currently approved by the system administrator. Once approved (if rejected, the workflow sets the state of the request as “closed inomplete” and ends here), the workflow continues to the third step, which is where the actual API call to EmpowerID is made with all required parameters. Please refer the integrations section of this document to know the details of the API. After the successful call, workflow marks the state of the RITM as “Closed Complete” and ends.

Data Model

The Orchestration Pack data model include custom Groups and Management Roles data, which is required for the EmpowerID workflows. In order to keep customer namespace uncluttered, EmpowerID does not use the default out-of-the-box tables for groups and roles as there are a lot of EmpowerID-specific attributes that need to be maintained. The data for these custom tables is updated by EmpowerID via inbound API.

Tables

Groups (x_36687_eid_groups)

Management Roles (x_36687_eid_management_roles)

Groups (x_36687_eid_groups)

Management Roles (x_36687_eid_management_roles)

Column Label

Column Name

Type

Column Label

Column Name

Type

Group GUID (PK)

group_guid

String

Management Role GUID (PK)

management_role_guid

String

Name

name

String

Name

name

String

Distinguished Name

distinguished_name

String

Friendly Name

friendly_name

String

Is High Security Group

is_high_security_goup

Boolean

Email

email

String

Auto Accept Join Leave Request

auto_accept_join_leave_requests

Boolean

Is High Security

is_high_security

Boolean

Group Usage Type Friendly Name

group_usage_type_friendly_name

String

Auto Accept Join Leave Request

auto_accept_join_leave_requests

Boolean

Friendly Name

friendly_name

String

Requestable

requestable

Boolean

Logon Name

logon_name

String

Risk Factor Total

risk_factor_total

Integer

Account Store Friendly Name

account_store_friendly_name

String

Valid From

valid_from

Date/Time

Allow Join Requests

allow_join_requests

Boolean

Valid Until

valid_until

Date/Time

Email

email

String

Description

description

String

Valid From

valid_from

Date/Time

Instructions

instructions

String

Valid Until

valid_until

Date/Time

Owner Assignee ID

owner_assignee_id

String

Description

description

String

Owner Login Name

owner_login_name

String

Notes

notes

String

Owner Friendly Name

owner_friendly_name

String

Owner Assignee ID

owner_assignee_id

String

Owner Email

owner_email

String

Owner Login Name

owner_login_name

String

Extension Attribute 1

extension_attribute_1

String

Owner Friendly Name

owner_friendly_name

String

Extension Attribute 2

extension_atrtibute_2

String

Owner Email

owner_email

String

Extension Attribute 3

extension_attribute_3

String

Extension Attribute 1

extension_attribute_1

String

Extension Attribute 4

extension_attribute_4

String

Extension Attribute 2

extension_attribute_2

String

Extension Attribute 5

extension_attribute_5

String

Extension Attribute 3

extension_attribute_3

String

Extension Attribute 6

extension_attribute_6

String

Extension Attribute 4

extension_attribute_4

String

Extension Attribute 7

extension_attribute_7

String

Extension Attribute 5

extension_attribute_5

String

Extension Attribute 8

extension_attribute_8

String

Extension Attribute 6

extension_attribute_6

String

Extension Attribute 9

extension_attribute_9

String

Extension Attribute 7

extension_attribute_7

String

Extension Attribute 10

extension_attribute_10

String

Extension Attribute 8

extension_attribute_8

String

Extension Attribute 11

extension_attribute_11

String

Extension Attribute 9

extension_attribute_9

String

Extension Attribute 12

extension_attribute_12

String

Extension Attribute 10

extension_attribute_10

String

Extension Attribute 13

extension_attribute_13

String

Extension Attribute 11

extension_attribute_11

String

Extension Attribute 14

extension_attribute_14

String

Extension Attribute 12

extension_attribute_12

String

Extension Attribute 15

extension_attribute_15

String

Extension Attribute 13

extension_attribute_13

String

Sys ID

sys_id

Sys ID (GUID)

Extension Attribute 14

extension_attribute_14

String

Updates

sys_mod_count

Integer

Extension Attribute 15

extension_attribute_15

String

Updated By

sys_updated_by

String

Sys ID

sys_id

Sys ID (GUID)

Updated

sys_updated_by

String

Updates

sys_mod_count

Integer

 

 

 

Updated By

sys_updated_by

String

 

 

 

Updated

sys_updated_by

String

 

 

 

Integrations

The EmpowerID Orchestration Pack has a number of inbound and outbound integration APIs defined. These integrations form the core of communication between ServiceNow and EmpowerID. The API includes the following HTTP methods for the EmpowerID components affected by the activities and workflows of the Orchestration Pack. This information is included as reference material. To view it, expand the headings.

 

Authentication

Use basic authentication and admin user’s credentials

Read Management Roles

GetMgmtRolesGUID

This endpoint retrieves a list of Management Roles currently present in ServiceNow.

HTTP Request

Method: GET

1 GET https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/getMgmtRolesGuid

Header Key/Value Pairs

Key

Value

Key

Value

X-UserToken

Your access token

Accept

application/json

Content-Type

application/json

Response

Status Code 200 OK

Header Key/Value Pairs

Key

Value

Key

Value

Cache-Control

Your access token

Content-Encoding

gzip

Content-Type

application/json;charsetUTF-8

Date

Date / Time GMT

Expires

0

Pragma

no-store,no-cache

Server

ServiceNow

Strict-Transport-Security

max-age63072000; includeSubDomains

Transfer-Encoding

chunked

X-Is-Logged-In

true

X-Transaction-Id

85d3c5addb2u8

Response Body

JSON object containing a list of Management Role GUIDs.

cURL Example

1 2 3 4 curl "https://YourServiceNowInstance/api/x_36687_eid/eid/getMgmtRolesGuid" \ --request GET \ --header "Accept:application/json" \ --user 'admin':'admin'

 

Read Management Groups

GetMgmtGroupsGUID

This endpoint retrieves a list of Management Groups currently present in ServiceNow.

HTTP Request

Method: GET

1 GET https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/getMgmtGroupsGuid

Header Key/Value Pairs

Key

Value

Key

Value

X-UserToken

Your access token

Accept

application/json

Content-Type

application/json

Response

Status Code 200 OK

Header Key/Value Pairs

Key

Value

Key

Value

Cache-Control

Your access token

Content-Encoding

gzip

Content-Type

application/json;charsetUTF-8

Date

Date / Time GMT

Expires

0

Pragma

no-store,no-cache

Server

ServiceNow

Strict-Transport-Security

max-age63072000; includeSubDomains

Transfer-Encoding

chunked

X-Is-Logged-In

true

X-Transaction-Id

85d3c5addb2u8

Response Body

JSON object containing a list of Management Group GUIDs

cURL Example

1 2 3 4 curl "https://YourServiceNowInstance/api/x_36687_eid/eid/getMgmtGroupsGuid" \ --request GET \ --header "Accept:application/json" \ --user 'admin':'admin'

 

Create Management Roles

MgmtRoles

This endpoint is used to create / push Management Roles from EmpowerID to ServiceNow

HTTP Request

Method: POST

1 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/mgmtroles

Request Data

Request data is sent to the API in JSON format.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 [ //Array of records { ‘<column name>’: ‘<value>’ 'management_role_guid': 'd9896948-b708-420e-ae6c-4cb038180159', 'friendly_name':'Friendly Name Five', 'valid_from': '2018-07-31 21:43:11', 'valid_until': '2018-08-22 21:43:11', 'description': 'Test Description Five', 'name': 'Five Management Role', . . . }, { 'management_role_guid': 'd9896948-b908-420e-ae6c-4cb038180159', 'friendly_name':'Friendly Name Six', 'valid_from': '2018-07-31 21:43:11', 'valid_until': '2018-08-22 21:43:11', 'description': 'Test Description Six' }, . . . ]

Element

Description

Type

Required

Element

Description

Type

Required

management_role_guid

GUID of the Management Role

String

Yes

friendly_name

Display Name of the Management Role

String

Yes

valid_from

Beginning date and time the Management Role is valid

Date/Time

Yes

valid_until

Ending date and time the Management Role is valid

Date/Time

Yes

description

Description of the Management Role

String

Yes

name

Name of the Management Role

String

Yes

auto_accept_join_leave_requests

Accept join and leave requests without requiring approval

Boolean

Yes

email

Email address for the Management Role

String

Yes

instructions

Instructions about the Management Role

String

Yes

is_high_security

Is the role high security?

Boolean

Yes

owner_assignee_id

ID of the EmpowerID Person owning the Management Role

Integer

Yes

owner_email

Email address of the EmpowerID Person owning the Management Role

String

Yes

owner_friendly_name

Friendly Name of the EmpowerID Person owning the Management Role

String

Yes

owner_logon_name

Logon Name of the EmpowerID Person owning the Management Role

String

Yes

requestable

Can users request access to the role?

Boolean

Yes

risk_factor_total

Risk factor of the role

Integer

Yes

extension_attribute_1

Extension attribute

String

Yes

extension_attribute_2

Extension attribute

String

Yes

extension_attribute_3

Extension attribute

String

Yes

extension_attribute_4

Extension attribute

String

Yes

extension_attribute_5

Extension attribute

String

Yes

extension_attribute_6

Extension attribute

String

Yes

extension_attribute_7

Extension attribute

String

Yes

extension_attribute_8

Extension attribute

String

Yes

extension_attribute_9

Extension attribute

String

Yes

extension_attribute_10

Extension attribute

String

Yes

extension_attribute_11

Extension attribute

String

Yes

extension_attribute_12

Extension attribute

String

Yes

extension_attribute_13

Extension attribute

String

Yes

extension_attribute_14

Extension attribute

String

Yes

extension_attribute_15

Extension attribute

String

Yes

 

Create Management Groups

MgmtGroups

This endpoint is used to create / push Management Groups from EmpowerID to ServiceNow

HTTP Request

Method: POST

1 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/mgmtgroups

Request Data

Request data is sent to the API in JSON format.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 [ //Array of records { ‘<column name>’: ‘<value>’ 'group_guid': 'd9896948-b708-420e-ae6c-4cb038180159', 'friendly_name':'Friendly Name Five', 'valid_from': '2018-07-31 21:43:11', 'valid_until': '2018-08-22 21:43:11', 'description': 'Test Description Five', 'name': 'Five Group', . . . }, { 'management_role_guid': 'd9896948-b908-420e-ae6c-4cb038180159', 'friendly_name':'Friendly Name Six', 'valid_from': '2018-07-31 21:43:11', 'valid_until': '2018-08-22 21:43:11', 'description': 'Test Description Six' }, . . . ]

Element

Description

Type

Required

Element

Description

Type

Required

group_guid

GUID of the group

String

Yes

friendly_name

Display Name of the group

String

Yes

distinguished_name

Distinguished name of the group

String

Yes

account_store_distinguished_name

Distinguished name of the account store the group belongs to

String

Yes

valid_from

Beginning date and time the group is valid

Date/Time

Yes

valid_until

Ending date and time the group is valid

Date/Time

Yes

description

Description of the group

String

Yes

name

Name of the group

String

Yes

allow_join_requests

Can users request to join the group?

Boolean

Yes

auto_accept_join_leave_requests

Accept join and leave requests without requiring approval

Boolean

Yes

email

Email address of the group

String

Yes

notes

Notes about the group

String

Yes

is_high_security_group

Is the group high security?

Boolean

Yes

owner_assignee_id

ID of the EmpowerID Person owning the group

Integer

Yes

owner_email

Email address of the EmpowerID Person owning the group

String

Yes

owner_friendly_name

Friendly Name of the EmpowerID Person owning the group

String

Yes

owner_logon_name

Logon Name of the EmpowerID Person owning the group

String

Yes

extension_attribute_1

Extension attribute

String

Yes

extension_attribute_2

Extension attribute

String

Yes

extension_attribute_3

Extension attribute

String

Yes

extension_attribute_4

Extension attribute

String

Yes

extension_attribute_5

Extension attribute

String

Yes

extension_attribute_6

Extension attribute

String

Yes

extension_attribute_7

Extension attribute

String

Yes

extension_attribute_8

Extension attribute

String

Yes

extension_attribute_9

Extension attribute

String

Yes

extension_attribute_10

Extension attribute

String

Yes

extension_attribute_11

Extension attribute

String

Yes

extension_attribute_12

Extension attribute

String

Yes

extension_attribute_13

Extension attribute

String

Yes

extension_attribute_14

Extension attribute

String

Yes

extension_attribute_15

Extension attribute

String

Yes

 

Delete Management Roles

deleteMgmtRoles

Use this endpoint to delete EmpowerID Management Roles currently present in ServiceNow.

HTTP Request

Method: POST

1 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/deleteMgmtRoles

Header Key/Value Pairs

Key

Value

Key

Value

X-UserToken

Your access token

Accept

application/json

Content-Type

application/json

Response

Status Code 200 OK

Header Key/Value Pairs

Key

Value

Key

Value

Content-Encoding

gzip

Date

Date / Time GMT

Server

ServiceNow

Strict-Transport-Security

max-age63072000; includeSubDomains

Transfer-Encoding

chunked

X-Is-Logged-In

true

X-Transaction-Id

85d3c5addb2u8

 

cURL Example

1 2 3 4 curl "https://YourServiceNowInstance/api/x_36687_eid/eid/deleteMgmtRoles" \ --request POST \ --header "Accept:application/json" \ --user 'admin':'admin'

 

Delete Management Groups

deleteMgmtGroups

Use this endpoint to delete EmpowerID Groups currently present in ServiceNow.

HTTP Request

Method: POST

1 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/deleteMgmtGroups

Header Key/Value Pairs

Key

Value

Key

Value

X-UserToken

Your access token

Accept

application/json

Content-Type

application/json

Response

Status Code 200 OK

Header Key/Value Pairs

Key

Value

Key

Value

Content-Encoding

gzip

Date

Date / Time GMT

Server

ServiceNow

Strict-Transport-Security

max-age63072000; includeSubDomains

Transfer-Encoding

chunked

X-Is-Logged-In

true

X-Transaction-Id

85d3c5addb2u8

 

cURL Example

1 2 3 4 curl "https://YourServiceNowInstance/api/x_36687_eid/eid/deleteMgmtGroups" \ --request POST \ --header "Accept:application/json" \ --user 'admin':'admin'

 

There are 3 main tasks performed in EmpowerID workflows within ServiceNow that are accomplished by making an API call to EmpowerID application. These tasks are as below:

  1. Create Employee

  2. Assign Group

  3. Assign Management Role

To invoke the above API calls, the identity making the call must have a valid token. For information on getting a token, see Getting an Access Token.

Create Employee

HTTP Method: POST

Endpoint

1 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start

Header Key/Value Pairs

Key

Value

Key

Value

Authorization

Bearer ${token}

X-EmpowerID-API-Key

f0f46cce-7cd1-4c34-8f7e-d54e96a2ab41

Content-Type

application/json

Request Data

Request data is sent to the API in JSON format.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "Name": "SNOWCreatePersonAdvanced", "InputParameters": { "TargetPerson" : { "LastName": "${FirstName}", "FirstName": "${LastName}", "Password": "${Password}", "Email": "${Email}", "Login": "${Username}" }, "GroupsToAddGuids" : "${MgmtGroupsToAdd}", "GroupRequestInitiator" : "${GroupRequestInitiator}", "GroupRequestApprover" : "${GroupRequestApprover}", "GroupStartAccess" : "${GroupStartAccess}", "GroupEndAccess" : "${GroupEndAccess}", "ManagementRoleToJoinGuids" : "${MgmtRolesToAdd}", "ManagementRoleRequestInitiator" : "${RolesRequestInitiator}", "ManagementRoleRequestApprover" : "${RolesRequestApprover}", "ManagementRoleStartAccess" : "${RoleStartAccess}", "ManagementRoleEndAccess" : "${RoleEndAccess}", "AccountStoreGUID" : "${AccountStoreGUID}" } }

 

Assign Group

HTTP Method: POST

Endpoint

1 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start

Header Key/Value Pairs

Key

Value

Key

Value

Authorization

Bearer ${token}

X-EmpowerID-API-Key

f0f46cce-7cd1-4c34-8f7e-d54e96a2ab41

Content-Type

application/json

Request Data

Request data is sent to the API in JSON format.

1 2 3 4 5 6 7 8 9 10 11 12 { "Name": "SnowUpdatePersonDirectAssignment", "InputParameters": { "TargetPersonLogonName" : "${TargetPersonLogin}", "GroupsToAddGuids" : "${GroupToAssign}", "GroupsToRemoveGuids" : "${GroupsToRemove}", "RequestInitiator" : "${Requester}", "RequestApprover" : "${Approver}", "AccountStoreGUID" : "F4047F57-0AFE-478D-BB2B-2E5F6E8C50FE" } }

 

Assign Management Role

HTTP Method: POST

Endpoint

1 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start

Header Key/Value Pairs

Key

Value

Key

Value

Authorization

Bearer ${token}

X-EmpowerID-API-Key

f0f46cce-7cd1-4c34-8f7e-d54e96a2ab41

Content-Type

application/json

Request Data

Request data is sent to the API in JSON format.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "Name": "SNOWUpdatePersonMgmtRole", "InputParameters": { "TargetPersonLogonName" : "${TargetPersonLogin}", "ManagementRoleToJoinGuids" : "${ManagementRoleToJoin}", "ManagementRoleToLeaveGuids" : "${ManagementRoleToLeave}", "RequestInitiator" : "${Requester}", "RequestApprover" : "${Approver}", "AccountStoreGUID" : "{AccountStoreGUID}", "StartAccess" : "${StartDate}", "EndAccess" : "${EndDate}" } }