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:

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@microfocus.com",
                "Location": "Europe",
                "CostCenter": "56232344",
                "Email": "robert.johnson@microfocus.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@microfocus.com",
                    "GroupB@microfocus.com"
                ]
            }
        },
        {
            "properties": {
                "FirstName": "Charles",
                "LastName": "Walker",
                "OfficePhoneNumber": "9876",
                "MobilePhoneNumber": "",
                "Upn": "charles.walker@microfocus.com",
                "Manager": "susan.white@microfocus.com",
                "Location": "Poland",
                "CostCenter": "56232344",
                "Email": "charles.walker@microfocus.com"
            },
            "roles": {
                "REPLACE": [
                    "role3",
                    "role4"
                ]
            },
            "licenses": {
                "REPLACE": [
                    {
                        "type": "Premium edition named user",
                        "capacity": "5"
                    }
                ]
            },
            "functionalGroups": {
                "REMOVE": [
                    "GroupA@microfocus.com",
                    "GroupB@microfocus.com"
                ],
                "ADD": [
                    "GroupC@microfocus.com"
                ]
            },
            "orgGroup": {
                "ADD": "GroupD@microfocus.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.

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.

For DELETE operations, the JSON appears as follows:

{
    "operation":"DELETE",
    "users": [
        {
            "properties": {
                "Upn": "michael.brown@microfocus.com"
            }
        },
        {
            "properties": {
                "Upn": "lauren.davis@microfocus.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:

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@microfocus.com"
            },
            "upnDataType": "Customer_UID",
            "roles": {
                "REPLACE": [
                    "role1",
                    "role2"
                ]
            }
        },
        {
            "properties": {
                "IsMaasUser": "FALSE",
                "LastName": "Walker",
                "Upn": "charles.walker@microfocus.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:

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@microfocus.com",
            "Status": " FINISHED_WITH_ERRORS",
            "ErrorMessage": "Did not assign the user to 
			      group[group1@microfocus.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@microfocus.com",
            "Status": " FAILED",
            "ErrorMessage": "Family name cannot be empty"
        }
    ]
}

Notes and limitations

The following notes and limitations apply to the Manage Persons API:

• The maximum bulk size supported is 100 users.
• A bulk cannot contain more than one entry for the same Upn.
• If the tenant includes more than one active license of the same type and capacity, the user is assigned the first of those licenses.

Related topics

• Overview of the REST API

• How to connect to the REST API

• Authentication endpoint service

• Record bulk update and collection APIs

• REST API queries

• REST API collection query protocol

• Analytics REST API

• REST API use case scenario - import REST API