Table Of Contents

Previous topic

Manage Accounts

Next topic

Manage Orders

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.

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.

  1. 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.

  2. The APS type:

  3. 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 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.

../../_images/ccp-vps-user.png

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.