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 GET https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/getMgmtRolesGuid Header Key/Value Pairs 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 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 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 GET https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/getMgmtGroupsGuid Header Key/Value Pairs 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 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 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 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. [ //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 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 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. [ //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 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 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/deleteMgmtRoles Header Key/Value Pairs 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 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 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 POST https://{FQDN_Of_Your_ServiceNow_Instance}/api/x_36687_eid/eid/deleteMgmtGroups Header Key/Value Pairs 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 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 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: Create Employee Assign Group 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 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start Header Key/Value Pairs 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. { "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 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start Header Key/Value Pairs 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. { "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 https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/services/v1/ExecuteWorkflow/start Header Key/Value Pairs 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. { "Name": "SNOWUpdatePersonMgmtRole", "InputParameters": { "TargetPersonLogonName" : "${TargetPersonLogin}", "ManagementRoleToJoinGuids" : "${ManagementRoleToJoin}", "ManagementRoleToLeaveGuids" : "${ManagementRoleToLeave}", "RequestInitiator" : "${Requester}", "RequestApprover" : "${Approver}", "AccountStoreGUID" : "{AccountStoreGUID}", "StartAccess" : "${StartDate}", "EndAccess" : "${EndDate}" } }