PAUser

This is the base APS type for other platform user types.

GraphViz

Schema

The considered APS type (download) extends the User APS type(s) and looks as follows:

{
  "name": "PAUser",
  "id": "http://parallels.com/aps/types/pa/user/1.2",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/user/1.0"
  ],
  "relations": {
    "organization": {
      "type": "http://aps-standard.org/types/core/account/1.0",
      "required": true
    }
  },
  "properties": {
    "memberId": {
      "type": "integer",
      "description": "Member id",
      "final": true
    },
    "userId": {
      "type": "integer",
      "description": "User id",
      "final": true
    },
    "subscriptionId": {
      "type": "integer",
      "description": "Subscription id"
    },
    "isAccountAdmin": {
      "type": "boolean"
    },
    "disabled": {
      "type": "boolean"
    },
    "locked": {
      "type": "boolean",
      "readonly": true,
      "default": "false"
    },
    "roles": {
      "type": "array",
      "description": "List of assigned roles",
      "items": {
        "type": "integer"
      }
    },
    "servicesMode": {
      "type": "string",
      "required": true,
      "default": "NONE",
      "enum": [
        "NONE",
        "PRIVATE",
        "PUBLIC"
      ],
      "enumTitles": [
        "No services assigned.",
        "Only services from the private subscription assigned to the user.",
        "Services from public subscriptions assigned to the user."
      ]
    },
    "serviceReferrerId": {
      "type": "string"
    },
    "invitationDate": {
      "type": "string",
      "readonly": true,
      "format": "date-time"
    }
  },
  "operations": {
    "invite": {
      "path": "invite",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "activate": {
      "path": "activate",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "resetPassword": {
      "path": "resetPassword",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "unlock": {
      "path": "unlock",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "disable": {
      "path": "disable",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "enable": {
      "path": "enable",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "loginHistory": {
      "path": "loginHistory",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "UserLoginHistoryItem"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "setAvatar": {
      "path": "avatar",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      }
    },
    "removeAvatar": {
      "path": "avatar",
      "verb": "DELETE",
      "errorResponse": {
        "type": "object"
      }
    },
    "listPrivileges": {
      "path": "privileges",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    }
  },
  "structures": {
    "UserLoginHistoryItem": {
      "type": "object",
      "properties": {
        "loginTime": {
          "type": "string",
          "format": "date-time"
        },
        "ipAddress": {
          "type": "string"
        }
      }
    }
  }
}

The APS type is used to manage a collection of APS resources. To get a list of resources from that collection, use the following API call:

GET  /aps/2/collections/pa-users?<RQL-filter>

Properties

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

memberId

Integer

Not Required Final

The staff member ID, unique in scope of all users with administrative privileges in the platform.

userId

Integer

Not Required Final

The user ID, unique in scope of all users in the platform.

subscriptionId

Integer

Not Required

The platform internal ID of the subscription that the user was created from. The subscription is also known as the private subscription for the user.

isAccountAdmin

Boolean

Not Required

If true, the user is granted the administrative privileges in the control panel. Otherwise, this is a service user (service consumer).

disabled

Boolean

Not Required

The flag that shows if the user is inactive (true) or active (false).

locked

Boolean

Not Required Read Only

false

The lock flag that shows if the password protection system locked the user’s access to the platform UI (true) or not (false).

roles

Array of Integer

Not Required

Get a list of the user roles.

servicesMode

Enum

Required

NONE

| Specify which of the following service types is assigned to the user:
NONE – no services assigned.
PRIVATE – at least one service from the private subscription assigned.
PUBLIC – only services from public (non-private) subscriptions assigned.

Service mode:
NONE - No services are assigned to the user.
PRIVATE - Only services from the private subscription are assigned to the user.
PUBLIC - Services from public subscriptions are assigned to the user.

serviceReferrerId

String

Not Required

Service referrer ID.

invitationDate

String

Not Required Read Only

Date and time when the invitation was sent to the user.

Relationship

NAME

TYPE

REQUIRED

DESCRIPTION

organization

Account

Yes

The account representation (http://aps-standard.org/types/core/account/1.0) the user works for.

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

invite

POST

/invite

If successful, this method returns the 200 OK standard status code.

Send an invitation to the newly created user.

activate

POST

/activate

If successful, this method returns the 200 OK standard status code.

Activate the user.

resetPassword

POST

/resetPassword

If successful, this method returns the 200 OK standard status code.

Send an email notification to the user. The notification contains a URL to the user panel where the user can reset their password.

unlock

POST

/unlock

If successful, this method returns the 200 OK standard status code.

Unlock the platform access for the user enforced by the password protection mechanism.

disable

POST

/disable

If successful, this method returns the 200 OK standard status code.

Disable the user and the related services.

enable

POST

/enable

If successful, this method returns the 200 OK standard status code.

Enable the user and the related services.

loginHistory

GET

/loginHistory

If successful, this method returns a list of the user login history in the response body using the (date-time, IP address) format.

Get the login history of the user.

setAvatar

PUT

/avatar

If successful, this method returns the 200 OK standard status code.

Update the “avatar” object (for example, photo) of the user.

removeAvatar

DELETE

/avatar

If successful, this method returns the 200 OK standard status code.

Delete the “avatar” object (for example, photo) of the user.

listPrivileges

GET

/privileges

If successful, this method returns a list of user’s privileges in the response body.

Get a list of the user privileges.

invite

HTTP Request

POST /aps/2/resources/{aps-id}/invite

Description

Send an invitation to the newly created user.

Returns

If successful, this method returns the 200 OK standard status code.

activate

HTTP Request

POST /aps/2/resources/{aps-id}/activate

Description

Activate the user.

Returns

If successful, this method returns the 200 OK standard status code.

resetPassword

HTTP Request

POST /aps/2/resources/{aps-id}/resetPassword

Description

Send an email notification to the user. The notification contains a URL to the user panel where the user can reset their password.

Returns

If successful, this method returns the 200 OK standard status code.

unlock

HTTP Request

POST /aps/2/resources/{aps-id}/unlock

Description

Unlock the platform access for the user enforced by the password protection mechanism.

Returns

If successful, this method returns the 200 OK standard status code.

disable

HTTP Request

POST /aps/2/resources/{aps-id}/disable

Description

Disable the user and the related services.

Returns

If successful, this method returns the 200 OK standard status code.

enable

HTTP Request

POST /aps/2/resources/{aps-id}/enable

Description

Enable the user and the related services.

Returns

If successful, this method returns the 200 OK standard status code.

loginHistory

HTTP Request

GET /aps/2/resources/{aps-id}/loginHistory

Description

Get the login history of the user.

Returns

If successful, this method returns a list of the user login history in the response body using the (date-time, IP address) format.

setAvatar

HTTP Request

PUT /aps/2/resources/{aps-id}/avatar

Description

Update the “avatar” object (for example, photo) of the user.

Returns

If successful, this method returns the 200 OK standard status code.

removeAvatar

HTTP Request

DELETE /aps/2/resources/{aps-id}/avatar

Description

Delete the “avatar” object (for example, photo) of the user.

Returns

If successful, this method returns the 200 OK standard status code.

listPrivileges

HTTP Request

GET /aps/2/resources/{aps-id}/privileges

Description

Get a list of the user privileges.

Returns

If successful, this method returns a list of user’s privileges in the response body.

Structures

UserLoginHistoryItem

An item in the user login history.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

loginTime

String

Not Required

The date of the user login.

ipAddress

String

Not Required

IP address of the user’s computer.

Examples

Get Users by Account

You must know the account APS ID to send the following request:

GET /aps/2/resources/6344049b-8763-417d-837b-490ba0896f41/users

Get User by Email Address

GET /aps/2/collections/pa-users?eq(email,isv1@aps.test)

Configure User

The following example illustrates how to change the phone number and postal address:

PUT /aps/2/resources/583f9d71-0e0b-4f65-8e76-56089de9378e

{
   "telCell": "+1 888 345-1234",
   "addressPostal": {
      "streetAddress":"88, ISV users",
      "locality":"Herndon",
      "region":"VA",
      "countryName":"US",
      "postalCode":"54387"
   }
}

In case of success, the return code must be “200 OK” and the returned payload contains the JSON representation of the updated user resource.

Remove User

Sometimes it is necessary to remove a user resource from the platform, for example, when the represented user leaves a company registered in the platform. The respective request looks as follows:

DELETE /aps/2/resources/583f9d71-0e0b-4f65-8e76-56089de9378e

In case of success, the return code must be “204 No content”.

Invite User

There is a custom invite operation that sends an invitation by email to a specified user. To use that operation on the APS bus, an external system must be granted the POST operation on the http://parallels.com/aps/types/pa/service-user and http://parallels.com/aps/types/pa/admin-user APS types.

A REST request must contain the user APS ID in the URL:

POST /aps/2/resources/c3c20ee8-8a41-4f8f-99c2-8f4b7d412595/invite

In case of success, the APS controller returns “200 OK” without body.

Activate User

There is a custom activate operation that allows an external system to make a user active. To use that operation on the APS bus, an external system must be granted the POST operation on the http://parallels.com/aps/types/pa/service-user and http://parallels.com/aps/types/pa/admin-user APS types.

A REST request must contain the user APS ID in the URL:

POST /aps/2/resources/c3c20ee8-8a41-4f8f-99c2-8f4b7d412595/activate

In case of success, the APS controller returns “200 OK” without body.