Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

Service Management

You are here: Advanced > Developer reference > Manage Persons API

Manage Persons API

The Manage Persons API enables you to create, update, and delete users in Suite Administration and sync them with Service Management. The Manage Persons API is a bulk create/update/delete API. A bulk processing request gets a JSON object which contains record data and an operation to process. A bulk may contain multiple records and relationship types but only a single operation.

The JSON for the Create operation must contain the following mandatory properties for each record:

Upn
First name (must be non-empty)
Last name (must be non-empty)
Office Phone Number (must be non-empty)
Email (must be non-empty)

For the Update and Delete operations, only Upn is mandatory.

Authentication type property can only be included in Create operation, three values are supported:

DB: User credentials are stored in IdM. This value is used by default if you do not include authentication type property in Create operation.
LDAP: User credentials are stored in LDAP servers.
SAML: User credentials are stored in federated identity providers.

You can also create and update contacts directly in Service Management.

You can use the Manage Persons API to assign roles, groups, and licenses for the created users by including this information in the JSON. The API supports all the properties of the Person record type.

Create/Update/Delete users JSON structure

Enter the following POST request URI:

https://<serverAddress>/rest/<tenant>/ums/managePersons

where:

tenant represents the tenant ID. The tenant ID can be copied from the Main menu.

The request is followed by a JSON containing the operation and user information. For Create or Update operations, the JSON appears as follows:

{
    "operation": "CREATE_OR_UPDATE",
    "users": [
        {
            "properties": {
                "FirstName": "Robert",
                "LastName": "Johnson",
                "OfficePhoneNumber": "1234",
                "MobilePhoneNumber": "9876543",
                "HomePhoneNumber": "9876543",
                "Upn": "u5627927",

                "Manager": "susan.white@hpe.com",
                "Location": "Europe",
                "CostCenter": "56232344",
                "Email": "robert.johnson@hpe.com"
                "AuthenticationType": "LDAP"

            },
            "upnDataType": "Customer_UID",
            "roles": {
                "REPLACE": [
                    "role1",
                    "role2"
                ]
            },
            "licenses": {
                "REPLACE": [
                    {
                        "type": "Premium edition concurrent user",
                        "capacity": "5"
                    },
                    {
                        "type": "Express edition named user",
                        "capacity": "15"
                    }

                    {
                        "type": "Express edition concurrent user",
                        "capacity": "5"
                    },

                ]
            },
            "groups": {
                "REPLACE": [
                    "GroupA@hpe.com",
                    "GroupB@hpe.com"
                ]
            }
        },
        {
            "properties": {
                "FirstName": "Charles",
                "LastName": "Walker",
                "OfficePhoneNumber": "9876",
                "MobilePhoneNumber": "",
                "Upn": "charles.walker@hpe.com",
                "Manager": "susan.white@hpe.com",
                "Location": "Poland",
                "CostCenter": "56232344",
                "Email": "charles.walker@hpe.com"
            },
            "roles": {
                "REPLACE": [
                    "role3",
                    "role4"
                ]
            },
            "licenses": {
                "REPLACE": [
                    {
                        "type": "Premium edition named user",
                        "capacity": "5"
                    }
                ]
            },
            "functionalGroups": {
                "REMOVE": [
                    "GroupA@hpe.com",
                    "GroupB@hpe.com"
                ],
                "ADD": [
                    "GroupC@hpe.com"
                ]
            },
            "orgGroup": {
                "ADD": "GroupD@hpe.com"
            }
        }
    ]
}

To remove a specific field value, you can use empty string as value for this field in JSON in Update operation.

In the CREATE_OR_UPDATE operation, all the users in the bulk are created or updated in Suite Administration and synced to Service Management. Additional data, such as roles, groups, and licenses are assigned to them.

There are two options for assigning groups to users:

You can add organizational groups and functional groups separately, using orgGroup and functionalGroups respectively for each section. You can assign multiple functional groups but only one organizational group.
You can add all groups together, using groups.

Note For the roles, groups, and licenses, the following commands are supported:

ADD
REMOVE
REPLACE

The ADD and REMOVE commands cannot be used along with the REPLACE command.

In the above example, the upnDataType for the first user is set to customerUID. This assigns the value in the UPN property to the customerUID field of the user created in Suite Administration. The value in the Email property is assigned to the login name for the user in Suite Administration.

For the second user, the upnDataType is not specified. In this case, the value in the UPN property is assigned to the login name for the user created in Suite Administration. The customerUID field for the user is empty.

The additional data which is updated in Service Management, can be referenced by an alias. For any person or group, the API attempts to identify the record by its Upn. If no such record is found, it attempts to find a record with a matching record ID. For a location, if the API does not identify the location by its name, it attempts to find a location with a matching record ID.

If the user exists in Suite Administration but is assigned to a different tenant, the API assigns the user to the new tenant in addition.

Note If a user was created or updated in Suite Administration and synced successfully to Service Management, but an error occurred when assigning additional data, the user remains in Suite Administration and Service Management. The status in the result will indicate exactly where the failure occurred.

For DELETE operations, the JSON appears as follows:

{
    "operation":"DELETE",
    "users": [
        {
            "properties": {
                "Upn": "michael.brown@hpe.com"
            }
        },
        {
            "properties": {
                "Upn": "lauren.davis@hpe.com"
            }
        }
    ]
}

If the authentication type is DB, the users are deleted from Suite Administration and IdM.
If the authentication type is LDAP or SAML, the users are deleted from Suite Administration only.

In Service Management, the users lose their license assignments and become inactive contacts

For Create, Update, and Delete operations, the response JSON contains an ID for the operation:

{
“JobID”=”5654”
}

To view the status of the operation, see Get job status JSON structure.

Create/Update contacts JSON structure

Enter the following POST request URI:

https://<serverAddress>/rest/<tenant>/ums/managePersons

where:

tenant represents the tenant ID. The tenant ID can be copied from the Main menu.

The JSON for the Create contacts operation must contain the following mandatory properties for each record:

Upn
First name and/or Last name and/or Name
IsMaasUser must be set to FALSE

You can assign roles to a contact, but contacts cannot be assigned to groups or granted licenses.

The request is followed by a JSON containing the contact information. The JSON appears as follows:

{
    "operation": "CREATE_OR_UPDATE",
    "users": [
        {
            "properties": {
                "IsMaasUser": "FALSE",
                "FirstName": "Robert",
                "Upn": "u5627927",
                "Email": "robert.johnson@hpe.com"
            },
            "upnDataType": "Customer_UID",
            "roles": {
                "REPLACE": [
                    "role1",
                    "role2"
                ]
            }
        },
        {
            "properties": {
                "IsMaasUser": "FALSE",
                "LastName": "Walker",
                "Upn": "charles.walker@hpe.com"
            },
            "roles": {
                "REPLACE": [
                    "role3",
                    "role4"
                ]
            }
        }
    ]
}

All the contacts in the bulk are created or updated in Service Management.

The additional data which is updated in Service Management, can be referenced by an alias. For any person, the API attempts to identify the record by its Upn. If no such record is found, it attempts to find a record with a matching record ID. For a location, if the API does not identify the location by its name, it attempts to find a location with a matching record ID.

It is possible to send both users and contacts in the same JSON. The contacts are processed directly in Service Management and the users are added in Suite Administration and synced to Service Management.

The response JSON contains an ID for the operation:

{
“JobID”=”5654”
}

To view the status of the operation, see Get job status JSON structure.

Get job status JSON structure

To view the status of the Create, Update, or Delete job, run the following GET request URI:

https://<serverAddress>/rest/<tenant>/ums/managePersonsJobStatus/<JOB_ID>

where JOB_ID is the value returned by the Manage Persons API.

The response JSON contains the bulk status. The following are the possible bulk status values:

RUNNING or PENDING. The API is still in progress.
SUCCESS. The API completed successfully. All users were created, updated, or deleted without errors.
FINISHED WITH ERRORS. The API completed with at least one error. At least one user was created in Suite Administration.
FAILED. The API failed. No users were created, updated, or deleted.

For the individual users, the following are the possible status values:

FINISHED WITH ERRORS. The user was created in Suite Administration but the record properties, roles, licenses, or groups were not updated.
FAILED. The user was not created, updated, or deleted.

The following is an example of the structure of the response JSON for the FINISHED WITH ERRORS bulk status:

{
    "BulkStatus": " FINISHED_WITH_ERRORS",
    "Results": [
        {
            "Upn": "charles.walker@hpe.com",
            "Status": " FINISHED_WITH_ERRORS",
            "ErrorMessage": "Did not assign the user to 
			      group[group1@hpe.com], 
			      since it does not	exist"
        }
    ]
}

The following is an example of the structure of the response JSON for the FAILED bulk status:

{
    "BulkStatus": " FAILED",
    "Results": [
        {
            "Upn": "robert.johnson@hpe.com",
            "Status": " FAILED",
            "ErrorMessage": "Family name cannot be empty"
        }
    ]
}