TDD: WXP Alert Management Integration with ServiceNow

Introduction

The HP Workforce Experience Platform (WXP) Alert Management scoped application integrates HP WXP with ServiceNow. WXP sends device and fleet alerts to ServiceNow as incidents. When these incidents close, ServiceNow sends resolution updates back to HP WXP through Fastn.

This application does not poll HP WXP. It exposes two Scripted REST endpoints: one receives alerts, and the other returns configuration lookup data. The application stages incoming alert data and transforms it into records in the out-of-box (OOB) incident table. It also monitors incident closure and sends status updates back through the same Fastn connection.

HP WXP initiates inbound requests by posting alerts to ServiceNow. ServiceNow initiates outbound requests by posting status updates to HP WXP through Fastn. Each direction trusts a different party and uses different authentication controls. For more information, see Security Model.

HP WXP Alert Management, HP WXP Device Management, and HP WXP Event Management use the same design pattern. They share the Fastn integration broker, tenant-scoping model, and setup-widget conventions. Several implementation choices appear to have been adapted directly from Event Management. One error message still identifies Event Management instead of Alert Management. For more information, see Known Limitations.

This technical design document (TDD) describes the data model, synchronization in both directions, and security controls for the integration. It covers the following topics:

The following table lists the application scope, integration broker, target table, and status.

Attribute	Value
Application scope	`x_hpws_wrkfrcexpam`
Integration broker	Fastn
Target table	`incident`
Status	Active · v1

Architecture and Data Flow

The application supports inbound and outbound data flows. Both flows use the same tenant configuration and Fastn integration broker.

Receiving Alerts

HP WXP sends an alert batch through Fastn to the Scripted REST endpoint /api/x_hpws_wrkfrcexpam/alerts.

AlertIngest validates and stages the entire batch in the import set. The application then runs the Transform Map synchronously to create or update incidents in ServiceNow.

Sending Incident Resolution Updates

When an incident closes, the HP WXP AM: Close Incidents Business Rule calls AlertUtils.callAPI('Update Incident').

AlertUtils sends the status update to HP WXP through the same Fastn connection. A scheduled job retries updates for incidents that remain in a failed-update state. For more information, see Business Logic.

Data model

The application uses two custom tables. It also reads or writes data in ServiceNow platform tables, including incident, sys_user_group, and sys_choice. These platform tables are not owned by the application.

Tenant List

The Tenant List (x_hpws_wrkfrcexpam_tenant_list) table stores customer records. Business Rules on this table enforce that only one tenant is active at a time.

The following table lists the fields, data types, and descriptions for the Tenant List table.

FIELD	TYPE	NOTES
tenant	String	Stores the display name. The application matches this value against incident company data when an incident closes.
tenantid	String	Stores the Fastn tenant ID.
status	Choice
active	True/False	A Business Rule enforces that exactly one row has this value set to true.
show_warning	True/False	Controls the confirmation prompt displayed when a tenant is activated.

HP Alert Inc Import Set

The HP Alert Inc Import Set (x_hpws_wrkfrcexpam_hp_alert_inc_import_set) table extends Import Set Row.

Each staging column corresponds to a field in the inbound alert payload. The column name consists of the u_ prefix followed by the lowercase version of the camelCase key sent by HP WXP.

The following table lists the 24 staging columns, grouped by the information they store.

GROUP	COLUMNS
Identity	`u_id`, `u_displayid`, `u_tenantid`, `u_alertruleid`, `u_userid`
Classification	`u_type`, `u_subtype`, `u_category`, `u_subcategory`, `u_priority`, `u_impact`, `u_urgency`, `u_status`
Content	`u_title`, `u_description`, `u_sourcelocation`, `u_metadata`
Routing	`u_assignmentgroupid`
Context (JSON strings)	`u_companydetails`, `u_devicedetails`, `u_userdetails`
Timing	`u_createdat`, `u_occuredat`, `u_updatedat`

Integration Design

The application uses two Scripted REST resources for inbound integration and one REST message with two operations for outbound integration.

Inbound Integration

The following table lists the Scripted REST resources, HTTP methods, paths, and handlers.

Resource	Method	Path	Handler
Post alerts	POST	`/api/x_hpws_wrkfrcexpam/alerts`	`AlertIngest.importBatch()`
Get lookups	GET	`/api/x_hpws_wrkfrcexpam/lookups`	`AlertConfigLookups.getLookups()`

Receiving Alert Batches

The Post alerts resource accepts a request body in the format { "alerts": [...] }. It also accepts an array without the enclosing object.

The resource rejects the entire batch if any alert fails validation or if the batch contains more than 100 rows.

For an accepted batch, the application:

Creates a sys_import_set record.
Stages each row.
Runs GlideImportSetTransformer synchronously using the single registered Transform Map.

If HP WXP omits a field when sending an alert again, the application treats that field as unchanged. AlertIngest reads the last staged row with the same u_id and retains the previous value. If HP WXP explicitly sends an empty field, the application clears its value.

Retrieving Configuration Lookups

The Get lookups resource returns assignment groups and incident category and subcategory choices. HP WXP uses this data to populate its alert configuration screen.

The resource supports conditional requests. It generates a weak ETag from the latest update timestamp and row count of the relevant sys_user_group and sys_choice records.

If the configuration has not changed, the resource returns HTTP status code 304 without a response body.

Outbound Integration

The following table lists the operations, HTTP methods, and endpoints used in the outbound REST message.

Operation	Method	Endpoint
Update Incident	POST	`${base_url}/api/v1/updateIncident`
Get Customers of Partner	POST	`${base_url}/api/v1/getTenantsChildren`

Both operations use AlertUtils.callAPI(). This method reads base_url from a system property, retries requests up to three times, and sets the following Fastn authentication headers on each request:

x-fastn-api-key
fastn-space-id
x-fastn-space-tenantid

The x-fastn-space-tenantid header identifies the connection-level tenant configured during setup. This value is separate from the tenant IDs included in individual request bodies.

Note: If an outbound update fails, the Business Rule sets the incident’s correlation_id to "WrkfrcExp Update Failed". The Business Rule does not retry the update inline.
The Periodic: Retry Fixed Update scheduled job finds incidents with this value and resends the updates.

Security Model

Inbound and outbound requests trust different parties and use different authentication controls.

Roles

The source configuration lists the following application roles:

x_hpws_wrkfrcexpam.admin
.user
.tenant_list_user
.hp_alert_inc_import_set_user

Protecting Inbound Requests

Both Scripted REST resources are protected by a REST_Endpoint access control list (ACL). Each resource script also checks for the x_hpws_wrkfrcexpam.user role by calling gs.hasRole('x_hpws_wrkfrcexpam.user').

The resource script comment explains the reason for this additional check: an ACL can be deactivated on a customer instance.

On August 31, 2026, it was confirmed that an authenticated user without the required role could create and resolve incidents when the script-level check was absent. Sending an alert again with status: FIXED closes the matching incident when the Transform Map coalesces on u_id.

Neither endpoint identifies the missing role in the HTTP response. The application records this detail in the system log through gs.warn() instead. This approach avoids telling an unauthorized user which role to obtain through a 403 response.

Table ACLs

The following table lists the custom tables, ACL operations, and owners.

Table	Operations	Owner
`x_hpws_wrkfrcexpam_tenant_list`	Create, Read, Update, Delete	`jessica.braganza`
`x_hpws_wrkfrcexpam_hp_alert_inc_import_set`	Create, Read, Update, Delete	`aditi.khanna`

Business Logic

The application uses Business Rules, a Transform Map, Script Includes, and a scheduled job to process alerts, maintain tenant configuration, and send incident resolution updates.

Business Rules

The following table lists the Business Rules used in the application, their associated tables, and their purposes.

Name	Table	Purpose
HP WXP AM: Close Incidents	`incident`	Sends the `FIXED` status and notes back to HP WXP when an incident closes.
HP WXP AM: Enforce Single Tenant Active	`tenant_list`	Deactivates other rows when a tenant is activated.
HP WXP AM: Warn on Activation	`tenant_list`	Displays the confirmation prompt controlled by `show_warning`.
HP WXP AM Add / Remove Tenants Value	`tenant_list`	Keeps the `x_hpws_wrkfrcexpam.tenants` property synchronized with the state of the tenant rows.

Sending Updates When Incidents Close

The HP WXP AM: Close Incidents Business Rule runs only when origin_id.message_key is numeric. This condition identifies incidents associated with an HP WXP alert.

The rule determines the tenant by extracting the company name from origin_id.description and matching it against the active row in Tenant List.

Note: If the rule cannot identify a tenant, it adds a work note and marks the update as failed. It does not send a request with an empty tenant ID.

Transform Map

The HP WXP Alert to Incident Transform Map maps records from the import set to the incident table.

The Transform Map contains 11 field entries and uses scripts for almost all entries rather than direct field mappings. This approach resolves classification and routing fields using logic similar to AlertConfigLookups, instead of copying incoming values directly.

Script Includes

The following table lists the Script Includes used in the application and their purposes.

Name	Purpose
AlertIngest	Validates batches, stages data, runs the Transform Map synchronously, and retains previous values for omitted fields.
AlertConfigLookups	Returns assignment groups and category and subcategory choices. Supports caching through ETags.
AlertUtils	Sends outbound requests through Fastn and handles retries. Supports AJAX calls from Service Portal widgets.
WrkfrcExpAMCalibrationUtil	Checks connectivity after installation or from the setup page. The check is read-only and does not refresh tenants.

Scheduled Script Execution

The Periodic: Retry Fixed Update scheduled job retries incident updates that previously failed.

The job finds incidents with correlation_id set to "WrkfrcExp Update Failed" and resends their updates to HP WXP.

Portal UI

The application uses Service Portal widgets that follow the same setup-page conventions as the related applications. It also includes a guided setup wizard for onboarding. This wizard is not available in Device Management.

The following table lists the seven widgets identified in the source configuration and their purposes.

Name	Purpose
HP WXP Alert App Setup	Displays the landing page for application setup.
HP WXP AM Guided Setup Wizard	Guides users through onboarding.
HP WXP AM Setup Connection	Enables users to enter the API key, base URL, and space ID.
HP WXP AM Status	Checks current connectivity and validates the tenant configuration.
HP WXP AM Tenant Config	Reads and updates the active tenant list.
HP WXP AM Failure Notification	Configures the group and email for integration failure notifications.
HP WXP AM Header	Displays shared branding and navigation elements.

Known Limitations

The following limitations relate to error messages, tenant resolution logic, lookup response size, and alert batch size.

1. Incorrect Application Name in an Error Message

AlertUtils.callAPI() records the following connection-tenant error message:

“HP WXP Event Management: Integration failed”

The message identifies Event Management instead of Alert Management. This is a cosmetic naming issue, but it can mislead users reviewing the log during an incident.

2. Duplicated Tenant Resolution Logic

The company-name-to-tenant-ID lookup logic is duplicated in the HP WXP AM: Close Incidents Business Rule and the retry scheduled job.

Both components parse origin_id.description and match the company name against Tenant List. They do not use a shared helper.

The retry scheduled job also contains a commented-out earlier version of the same logic that is no longer used.

3. Lookup Responses Without a Size Limit

AlertConfigLookups.getLookups() returns the complete assignment group and choice lists without a size limit. The implementation assumes that the caller filters the results on the client side.

This approach is suitable for the current scale but should be reviewed if either list becomes large.

4. Batch Limit Without Pagination Guidance

AlertIngest.MAX_BATCH = 100 limits each alert batch to 100 rows. The application rejects a batch that exceeds this limit.

The error message identifies the limit. No additional pagination guidance is documented for the caller.

Compiled from the live instance configuration on September 10, 2026.

Contact Us

For any assistance, create a support case or email support@wxp.hp.com.