Page Comparison

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.

...

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 Service Now ServiceNow with the Orchestration Pack.

...

Expand

title	APIs Exposed by ServiceNow

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

Code Block
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

Code Block

language	text

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

Code Block
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

Code Block

language	text

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

Code Block
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.

Code Block

[ //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

Code Block
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.

Code Block

[ //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

Code Block
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

Code Block

language	text

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

Code Block
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

Code Block

language	text

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

Expand

title	EmpowerID APIs Consumed by ServiceNow

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

Code Block
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.

Code Block

{
  "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

Code Block
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.

Code Block

{
  "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

Code Block
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.

Code Block

{
  "Name": "SNOWUpdatePersonMgmtRole",
  "InputParameters":
  {
    "TargetPersonLogonName" : "${TargetPersonLogin}",
    "ManagementRoleToJoinGuids" : "${ManagementRoleToJoin}",
    "ManagementRoleToLeaveGuids" : "${ManagementRoleToLeave}",
	"RequestInitiator" : "${Requester}",
	"RequestApprover" : "${Approver}",
	"AccountStoreGUID" : "{AccountStoreGUID}",
     "StartAccess" : "${StartDate}",
     "EndAccess" : "${EndDate}"
  }
}

Versions Compared

Old Version 5

New Version Current

Key

Authentication

Read Management Roles

GetMgmtRolesGUID

HTTP Request

Response

Read Management Groups

GetMgmtGroupsGUID

HTTP Request

Response

Create Management Roles

MgmtRoles

HTTP Request

Request Data

Create Management Groups

MgmtGroups

HTTP Request

Request Data

Delete Management Roles

deleteMgmtRoles

HTTP Request

Response

Delete Management Groups

deleteMgmtGroups

HTTP Request

Response

Create Employee

HTTP Method: POST

Request Data

Assign Group

HTTP Method: POST

Request Data

Assign Management Role

HTTP Method: POST

Request Data