Use Case: User Onboarding

Many organisations use ServiceNow Service Portal forms to manage requests for employee access to Peoplesafe. This integration automates the process of manually re-entering that data into the Peoplesafe Nexus portal. By connecting ServiceNow directly to the Peoplesafe User Management API, you ensure that as soon as a request is approved, the user profile is provisioned instantly.

Note: This guide is intended for informational purposes and is not a replacement for official ServiceNow documentation. It does not provide an exhaustive list of all available data fields or configuration permutations. Instead, it serves as a high-level blueprint to demonstrate what is possible within the ServiceNow ecosystem and the Peoplesafe User Management API.

Integration Summary

If you are looking for the quick checklist, here is the high-level workflow for this integration:

• Trigger: User submits a ServiceNow Service Portal form.

• Authentication: Uses an Subscription-Key and Bearer Token from the Peoplesafe.

• Endpoint: POST to https://api.peoplesafe.io/user-management/person/create.

• Validation: Use a script to ensure phone numbers are in E.164 format (e.g., +44...) before sending.

• Conflict Management: Check for Status Code 409 to handle users who already exist in Nexus without failing the flow.

• Success: A Status Code 201 confirms the user has been provisioned.

1. Prerequisites

• Access to the Peoplesafe APIs: Contact your Account Manager to enable API permissions for your account.

• API Keys: You will need your unique Subscription Key and Authentication Key from the Peoplesafe Developer Portal.

• ServiceNow Permissions: You will need the admin or web_service_admin role.

2. ServiceNow Infrastructure

It helps to think of this integration as a three-part machine:

1. The Intake (The Form): This is what the employee sees. They fill in their name, email, and phone number.

2. The Engine (The Flow): This is the "brain" that wakes up when the form is submitted. It takes the information, cleans it up (validation), and decides when to send it to Peoplesafe.

3. The Messenger (The REST Message): This is the technical envelope. It holds the "Address" (API Endpoint), the "Key" (Authentication), and the "Letter" (The JSON data).

To build this integration, you will be using three core ServiceNow components:

1. The Trigger (Data Collection): You will typically create a Service Portal Form or a Record Producer. When a user hits "Submit," that data is stored in a ServiceNow table (e.g., a custom u_peoplesafe_requests table or the standard sys_user table).

2. The Engine (Flow Designer): This is the "No-Code" way to handle the push. You will create a Flow triggered by a "Record Created" event on your table, which then executes the REST Step.

3. The Connection (Authentication): While we use API Keys in this example, ServiceNow stores these securely in the Credentials [sys_auth_profile] table. This ensures your keys are encrypted and not hard-coded into scripts.

3. Data Mapping (Example)

The following fields represent a common baseline for user creation in Peoplesafe. For a full list of available attributes, refer to the Peoplesafe API Documentation.

4. ServiceNow Configuration Steps

Step 1: Create the REST Message

Navigate to System Web Services > Outbound > REST Message. This acts as the template for your communication with Peoplesafe.

1. Name: Peoplesafe Create User.

2. Endpoint: https://api.peoplesafe.io/user-management/person/create

3. Add a POST method.

4. In HTTP Headers, add your Ocp-Apim-Subscription-Key and Authorization: Bearer [Token].

Step 2: Define the JSON Payload

Add this to the Content field of your POST method. Variables ${variable} will be populated by your ServiceNow form:

{
    "person": {
        "userReference": "${user_ref}",
        "emailAddress": "${email}",
        "firstName": "${first_name}",
        "lastName": "${last_name}",
        "hasPortalAccess": ${portal_access},
        "sexAssignedAtBirth": "${sex}",
        "roles": [${role_id}],
        "contactPhoneNumbers": [
            {
                "type": 0,
                "number": "${phone_number}",
                "isPrimary": true
            }
        ],
        "assignedSubscriptionType": ${sub_type_id}
    },
    "withoutActivation": ${skip_activation}
}

5. Advanced Logic & Error Handling

Handling "409 Conflict" (Existing Users)

In Flow Designer, add an If block to evaluate the response. This prevents your automation from failing if a user is already registered.

The Condition Script:

// Get the status code from the REST response output
var statusCode = fd_data.step_name.status_code; 

if (statusCode == 201) {
    return "success";
} else if (statusCode == 409) {
    return "already_exists";
} else {
    return "error";
}

Pre-Flight Data Validation (Phone Numbers)

Peoplesafe strictly validates phone formats. Before sending your API request, it is recommended to sanitize the phone number using a script step in your Flow to ensure it follows the E.164 standard (e.g., +447123456789).

Example Sanitization Logic:

• Remove all spaces, brackets, and dashes.

• Ensure the string starts with a +.

• Convert leading 0 to the relevant country code (e.g., +44).

Why this is important:

• API Reliability: The Peoplesafe API validates phone numbers strictly. If a user enters "07123 456789" (with a space), the API call may fail.

• Global Standard: Converting numbers to E.164 format (e.g., +44...) ensures the user's phone can be reached by the Peoplesafe Alarm Receiving Centre.

6. Troubleshooting & Best Practices

• No Quotes for Integers/Booleans: Ensure ${sub_type_id} and ${portal_access} are not wrapped in quotes.

• Enum Accuracy: sexAssignedAtBirth is case-sensitive ("Male", not "male").

• Case Sensitivity: Convert email addresses to lowercase in ServiceNow before sending to prevent duplicate errors.