Manage Users¶

Many cloud applications provide services to be consumed by end users individually. The following scenario illustrates how to create and configure users of two different types and then create and assign a sample service as a resource to a user.

In this document:

Source Data
Preliminary Inspection
Create Users
Activate a User
Configure a User
Remove a User
Assign Services to Users
Conclusion

Source Data ¶

An account in the platform usually has two types of users - staff members and service users - as explained in Accounts and Users concepts. For both types of users, it is necessary to collect some source data before operating user resources.

You need to collect the following data.

The APS ID assigned to the new customer created in the Manage Accounts scenario.

You will link the customer with the new staff member using the users relationship collection in the abstract Account type.
The APS type:
- To create a staff member, use the PAAdminUser type from the Platform Types.
- To create a service user, use the PAServiceUser type from the Platform Types.
The set of properties.

The following table illustrates a list of properties required for user creation.

Property	Type	Sample value	Notes
`aps.type`	URI	`"http://parallels.com/aps/types/pa/admin-user/1.2"`	Must match the ID specified in PAAdminUser exactly.
`isAccountAdmin`	Boolean	`true` `false`	`true` when creating a staff member `false` when creating a service user
`login`	Mail address	“mw@aps.test”	A unique login name in the form of an email address.
`password`	String	“p@$$w0rd”	A password compliant with the password strength policy as configured in the PCP.
`email`	String	“isv1@aps.test”
`givenName`	String	“Mike”
`familyName`	String	“Wilson”
`telVoice`	String	“1(888)1234567”
`addressPostal`	Structure	{“streetAddress”:”11, ISVone”, “locality”:”Herndon”, “region”:”VA”, “countryName”:”us”, “postalCode”:”12345”}	Enter the full postal address as specified by the `http://aps-standard.org/types/core/contact/1.1#Address` structure in the abstract Contact type.

Note

Contact properties of the user APS type are declared in the inherited abstract Contact APS type.

The login and password properties are declared in the inherited abstract User APS type.

The following table illustrates the relationship required for creating a new user.

RELATION	APS type on the remote end	Notes
`organization`	`http://aps-standard.org/types/core/account/1.0`	Required relationship.

Preliminary Inspection ¶

Before you start creating a new user, verify if there is a user with similar properties to ensure the uniqueness of some properties.

Examples:

Get a list of all staff members:
```
GET /aps/2/collections/admin-users
```

Get a list of all service users:

GET /aps/2/collections/pa-service-users

Get a list of users linked with a certain account (you must know the account APS ID, see Account Lookup):
```
GET /aps/2/resources/6344049b-8763-417d-837b-490ba0896f41/users
```
Verify if the email address in the new user properties is already used by an existing user, for example:
```
GET /aps/2/collections/pa-users?eq(email,isv1@aps.test)
```

Create Users ¶

Create a Staff Member¶

The APS type used to create a staff member contains a required relationship with the account. One of the ways to provision such objects is to follow the Provisioning Resources with Required Links operation. The REST request specifies the customer APS ID in the URL to create a link to the customer’s users collection along with the creation of the user to whom the link leads:

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

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/admin-user/1.2"
   },
   "isAccountAdmin": true,
   "login": "mw@aps.test",
   "password": "p@$$w0rd",
   "email": "mw@aps.test",
   "givenName": "Mike",
   "familyName": "Wilson",
   "telVoice": "1(888)1234567",
   "addressPostal": {
      "streetAddress":"11, ISVone",
      "locality":"Herndon",
      "region":"VA",
      "countryName":"us",
      "postalCode":"12345"
   }
}

The response must look similar to:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/admin-user/1.2",
      "id": "1c8763a4-ed0e-470b-a24e-4e05c7efb61e",
      "status": "aps:ready",
      "revision": 4,
      "modified": "2016-09-27T08:11:34Z",
      "package": {
         "id": "e86ef200-5751-4c2c-b342-e65483ede6d0",
         "href": "/aps/2/packages/e86ef200-5751-4c2c-b342-e65483ede6d0"
      }
   },
   "addressPostal": {
      "countryName": "us",
      "locality": "Herndon",
      "postalCode": "12345",
      "region": "VA",
      "streetAddress": "11, ISVone"
   },
   "disabled": false,
   "displayName": "",
   "email": "mw@aps.test",
   "familyName": "Wilson",
   "fullName": "",
   "givenName": "Mike",
   "isAccountAdmin": true,
   "locale": "en_US",
   "locked": false,
   "login": "mw@aps.test",
   "memberId": 6,
   "servicesMode": "NONE",
   "telVoice": "1#888#1234567#",
   "userId": 6,
   "organization": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/6344049b-8763-417d-837b-490ba0896f41",
         "id": "6344049b-8763-417d-837b-490ba0896f41"
      }
   },
   "services": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/1c8763a4-ed0e-470b-a24e-4e05c7efb61e/services"
      }
   }
}

Create a Service User¶

The APS type used to create a user contains a required relationship with the account. One of the ways to provision such objects is to follow the Provisioning Resources with Required Links operation. The REST request must require the creation of a link to the users collection along with the creation of the user to whom the link leads:

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

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/service-user/1.2"
   },
   "isAccountAdmin": false,
   "login": "na@aps.test",
   "password": "p@$$w0rd",
   "email": "na@aps.test",
   "givenName": "Nick",
   "familyName": "Archer",
   "telVoice": "1(888)1230002",
   "addressPostal": {
      "streetAddress":"12, ISVusers",
      "locality":"Herndon",
      "region":"VA",
      "countryName":"us",
      "postalCode":"12345"
   }
}

The response must look similar to:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/service-user/1.2",
      "id": "e21e19e0-5951-43a7-8103-8c5606398379",
      "status": "aps:ready",
      "revision": 5,
      "modified": "2016-09-27T09:16:30Z",
      "package": {
         "id": "e86ef200-5751-4c2c-b342-e65483ede6d0",
         "href": "/aps/2/packages/e86ef200-5751-4c2c-b342-e65483ede6d0"
      }
   },
   "addressPostal": {
      "countryName": "us",
      "locality": "Herndon",
      "postalCode": "12345",
      "region": "VA",
      "streetAddress": "12, ISVusers"
   },
   "disabled": false,
   "displayName": "",
   "email": "an@aps.test",
   "familyName": "Archer",
   "fullName": "",
   "givenName": "Nick",
   "isAccountAdmin": false,
   "locale": "en_US",
   "locked": false,
   "login": "na@aps.test",
   "servicesMode": "NONE",
   "telVoice": "1#888#1230002#",
   "userId": 8,
   "organization": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/6344049b-8763-417d-837b-490ba0896f41",
         "id": "6344049b-8763-417d-837b-490ba0896f41"
      }
   },
   "services": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/e21e19e0-5951-43a7-8103-8c5606398379/services"
      }
   }
}

You can create as many users as necessary this way.

Create Multiple Inactive Users¶

There is a user management service whose methods are defined by the UserManagement APS type. Combined with the user creation method explained in the previous section, the user manager provides the following additional capabilities:

It allows bulk operations with users. The request body contains an array of user JSON representations.
It allows the creation of inactive users without assigning a password for them. The new users will be inactive if the REST request for creating them contains the custom "X-Options-Send-Invitation":true header.

To allow a system authenticated through the OAuth protocol to use this function, it must be granted the POST operation on the http://www.parallels.com/pa/pa-core-services APS type.

For each user, you must provide a unique APS ID in the form of GUID generated by, for example, the Online GUID Generator. Add the X-Options-Send-Invitation header if the new users must be inactive and must receive an invitation by email to log in to the control panel. As an example, you can create sample users by calling the following custom operation:

POST /aps/2/services/user-manager/users
Content-Type: application/json
X-Options-Send-Invitation: true

[
   {
      "aps": {
      "type": "http://parallels.com/aps/types/pa/admin-user/1.2",
            "id": "719f6815-1db7-4229-85d2-61f30ae8b9de"
      },
      "isAccountAdmin": true,
      "login": "jbakham@aps.test",
      "email": "jbakham@aps.test",
      "givenName": "Jeff",
      "familyName": "Bakham",
       "displayName": "Jeff Bakham",
      "telVoice": "1(888)1234567",
      "addressPostal": {
         "streetAddress":"11, ISVone",
         "locality":"Herndon",
         "region":"VA",
         "countryName":"us",
         "postalCode":"12345"
      },
      "organization": {
         "aps": {
            "id": "6344049b-8763-417d-837b-490ba0896f41"
         }
      }
   },
   {
      "aps": {
         "type": "http://parallels.com/aps/types/pa/service-user/1.2",
            "id": "548e2fa9-2444-4b64-ac97-cb97f0d1ca77"
      },
      "isAccountAdmin": false,
      "login": "tfisher@aps.test",
      "email": "tfisher@aps.test",
      "givenName": "Tom",
      "familyName": "Fisher",
       "displayName": "Tom Fisher",
      "telVoice": "1(888)1230002",
      "addressPostal": {
         "streetAddress":"12, ISVusers",
         "locality":"Herndon",
         "region":"VA",
         "countryName":"us",
         "postalCode":"12345"
      },
      "organization": {
         "aps": {
            "id": "6344049b-8763-417d-837b-490ba0896f41"
         }
      }
   }
]

In response, the APS controller must return the JSON representation of the created users. In the JSON representation of an inactive user, the invitationDate property is null. If you read the created user APS resource, the invitation property will show the date and time of the user creation.

Invite an Inactive User¶

When the platform creates an inactive user it sends an invitation to the email address of the user. The user can get access to the password setup view of the control panel where the user can set a new password and then log in the control panel. This procedure makes the user active in the platform.

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

If successful, the APS controller returns “200 OK” without body.

Activate a User ¶

A platform user can activate their user resource as explained in the previous section.

Also, 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

If successful, the APS controller returns “200 OK” without a body.

Configure a User ¶

In some cases, you might want to change some user properties in the platform. Firstly, collect the following data about the user:

The APS ID as explained earlier in the Preliminary Inspection section.
The properties to change.

The following example illustrates how to change a user’s 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"
   }
}

If successful, the return code will be “200 OK” and the returned payload will contain the JSON representation of the updated user resource.

To configure several users, the system can use the updateServiceUsers operation exposed by the user management service.

Remove a 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

If successful, the return code must be “204 No content”.

To remove several users, the system can use the deleteServiceUsers operation exposed by the user management service.

Assign Services to Users ¶

The next step in our scenario is assigning an application service to service users. For this, your test customer must be subscribed to the application services. In the following examples, the sample application allows a customer to create virtual private servers (VPSes) for service users. The subscription contains a limited number of various offers for creating VPSes. You have created a service user for whom the customer administrator (staff member) needs to create VPSes.

Source Data¶

Find the APS type of the sample service, for example, http://aps-standard.org/samples/suwizard1p/vps/1.0.

Note

A VPS must have a relationship with the following resources whose APS IDs you must collect before provisioning a VPS:

Service user
Offer
Management context in the subscription

The APS ID of the service user in the list of user:

GET /aps/2/collections/pa-service-users

or in the response when creating a new user. For example, the following response contains the APS ID of the user created earlier:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/service-user/1.2",
      "id": "e21e19e0-5951-43a7-8103-8c5606398379",
      /* ... */
   },
   /* ... */
}

The APS ID of the silver offer that will be related to the new VPS:

GET /aps/2/resources?implementing(http://aps-standard.org/samples/suwizard1p/offer/1.0),like(name,*Silver*)

The following response contains the APS ID of the silver offer created earlier:

HTTP/1.1 200 OK

[
   {
      "aps" : {
         "id":"8c0e2f65-8968-43f6-97ca-93ed7b7df9d1",
         /* ... */
      },
      /* ... */
   }
]

The APS ID of the management context that will be related to the VPS:

GET /aps/2/resources?implementing(http://aps-standard.org/samples/suwizard1p/context/1.0)

The response must contain only one resource of this type, since this is a singleton resource in a subscription:

HTTP/1.1 200 OK

[{"aps":{"id":"32ef5e79-1043-45db-a26d-21dcd4ef3661",/* ... */},/* ... */}]

The APS ID of the subscription whose limits must allow for creation of the VPS:
```
GET /aps/2/collections/pa-subscriptions
```
The following response contains the APS ID of the subscription created earlier:
```
HTTP/1.1 200 OK

[{"aps":{"id":"c315f4a9-1e00-4458-b3e9-95de5659b3d7",/* ... */},/* ... */}]
```

Preliminary Inspection¶

Before you start creating a new VPS, verify whether there is a VPS with similar properties and whether the respective resource usage did not reach its limit in the subscription.

Get a list of all service VPSes:

GET /aps/2/resources?implementing(http://aps-standard.org/samples/suwizard1p/vps/1.0)

Verify whether there is a VPS with a name similar to the name of the new VPS:

GET /aps/2/resources?implementing(http://aps-standard.org/samples/suwizard1p/vps/1.0),like(name,*VPS-101*)

Verify whether the silver offer usage did not reach the limit in the subscription. Use the subscription APS ID in the following request:

GET /aps/2/resources/c315f4a9-1e00-4458-b3e9-95de5659b3d7/resources

The following response shows that only 1 VPS out of 10 allowed is used:

HTTP/1.1 200 OK

[/* ... */{
   "id": "1000053"
   "title": "User Management - Silver VPS Configuration"
   "apsId": "8c0e2f65-8968-43f6-97ca-93ed7b7df9d1"
   "apsType": "http://aps-standard.org/samples/suwizard1p/offer/1.0"
   "usage": 1
   "limit": 10
   "unit": "unit"
},/* ... */]

Creating a Resource¶

A REST request for creating a new VPS must comply with the vps type investigated earlier. Most importantly, specify the required links with the management context, an offer, and a user, as well as to specify the subscription APS ID in the APS-Subscription-ID header.

POST /aps/2/resources

"APS-Subscription-ID": "c315f4a9-1e00-4458-b3e9-95de5659b3d7"

{
    "aps":{
    "type":"http://aps-standard.org/samples/suwizard1p/vps/1.0"
    },
    "name":"VPS-101",
    "state":"Stopped",
    "hardware":{
        "memory": 512,
        "diskspace": 64,
        "CPU":{
         "number": 2
        }
    },
    "platform":{
      "OS":{
          "name":"CentOS",
          "version": 7
        }
    },
   "userName":"Nick Archer",
   "offer":{
      "aps":{
         "id":"8c0e2f65-8968-43f6-97ca-93ed7b7df9d1"
      }
   },
   "context":{
      "aps":{
         "id":"32ef5e79-1043-45db-a26d-21dcd4ef3661"
      }
   },
   "user":{
      "aps":{
          "id":"e21e19e0-5951-43a7-8103-8c5606398379"
      }
   }
}

The response must look similar to this:

HTTP/1.1 200 OK

{
  "aps": {
    "type": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
    "id": "34540887-26ee-49fe-97ad-0fe067268ded",
    "status": "aps:ready",
    "revision": 3,
    "modified": "2016-09-28T09:57:55Z",
    "subscription": "c315f4a9-1e00-4458-b3e9-95de5659b3d7",
    "package": {
      "id": "0275d4b1-b8a9-4c2c-bd3c-b11fc3c45081",
      "href": "/aps/2/packages/0275d4b1-b8a9-4c2c-bd3c-b11fc3c45081"
    }
  },
  "hardware": {
    "CPU": {
      "number": 2
    },
    "diskspace": 64,
    "memory": 512
  },
  "name": "VPS-101",
  "platform": {
    "OS": {
      "name": "CentOS",
      "version": "7"
    }
  },
  "state": "Stopped",
  "userName": "Nick Archer",
  "context": {
    "aps": {
      "link": "strong",
      "href": "/aps/2/resources/32ef5e79-1043-45db-a26d-21dcd4ef3661",
      "id": "32ef5e79-1043-45db-a26d-21dcd4ef3661",
      "subscription": "c315f4a9-1e00-4458-b3e9-95de5659b3d7"
    }
  },
  "offer": {
    "aps": {
      "link": "strong",
      "href": "/aps/2/resources/8c0e2f65-8968-43f6-97ca-93ed7b7df9d1",
      "id": "8c0e2f65-8968-43f6-97ca-93ed7b7df9d1"
    }
  },
  "user": {
    "aps": {
      "link": "strong",
      "href": "/aps/2/resources/e21e19e0-5951-43a7-8103-8c5606398379",
      "id": "e21e19e0-5951-43a7-8103-8c5606398379"
    }
  }
}

Now your test user can use the newly created VPS.

Conclusion ¶

You are now experienced in creating and managing customer administrators (staff members) and service users. You have also created a new resource from the customer’s subscription and assigned it to a service user.

You can use additional verification of the performed operations:

Use the REST requests described in the Preliminary Inspection to find the difference.
Find the new users in the Provider Control Panel (PCP) by logging in to the PCP and navigating to System > Users to see a list of all users. Use filters and sort the list by columns to identify the new user.
Use the REST requests described in the Preliminary Inspection to find the new assigned resource.
Find the new VPS in the Customer Control Panel (CCP). For this aim, log in to CCP and open the VPS Management item in the navigation menu. In the list of servers, find the newly created VPS and examine the properties you have assigned to it.

← Manage Accounts

Verify Discounts →

CloudBlue Commerce API

Previous topic

Next topic

Manage Users¶

Source Data ¶

Preliminary Inspection ¶

Create Users ¶

Create a Staff Member¶

Create a Service User¶

Create Multiple Inactive Users¶

Invite an Inactive User¶

Activate a User ¶

Configure a User ¶

Remove a User ¶

Assign Services to Users ¶

Source Data¶

Preliminary Inspection¶

Creating a Resource¶

Conclusion ¶