Table Of Contents

Previous topic

Manage Accounts

Next topic

Manage Orders

Application Packaging Standard

Last updated 18-Mar-2019

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 get some source data before operating user resources.

You need to collect the following data.

  1. 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 standard Account type.

    If you do not have the customer APS ID yet, use one of the methods in the previous scenario to get it.

  2. APS type:

  3. Set of properties.

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

Property Type Sample value Notes
aps.type URI “http://parallels.com/aps/types/pa/admin-user/1.2” Exact match with the ID specified in PAAdminUser.
isAccountAdmin Boolean
true
false
true when creating a staff member
false when creating a service user
login Mail address “mw@aps.test” Unique login name in the form of email address.
password String “p@$$w0rd” A password compliant with the password strength policy as configured in 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 full postal address as specified by the http://aps-standard.org/types/core/contact/1.1#Address structure in the standard Contact type.

Note

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

The login and password properties are declared in the inherited standard 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/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 there is a user with the email address belonging to a new user, for example:

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

Create Users

Create 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 creation of the user to whom the link leads to:

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 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 creation of a link to the users collection along with creation of the user to whom the link leads to:

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"
    }
  }
}

The same way, you can create more users.

Create Multiple Inactive Users

There is a user management service whose methods are defined by the UserManagement APS type. Compared 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 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, for example, generated by the Online GUID Generator. Add the X-Options-Send-Invitation header if the new users must be inactive and must receive by email an invitation to log in to the control panel. For 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. A specific of an inactive user is that its JSON representation contains the invitationDate property whose value is null in the response. However, if you read the created user APS resource, the invitation property will show the date and time of the user creation.

Invite 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

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

Activate 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

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

Configure User

In some cases, you might want to change some user properties in the platform. Preliminary, you must collect the following data about the 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.

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

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

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

Assign Services to Users

In accordance with the scenario, the services provided by a sample application must be assigned to service users. Your test customer must be subscribed to the application services. In the following examples, the sample application allows creating 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) should create VPSes.

Source Data

Find out 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

  • APS ID of the service user:

    GET /aps/2/collections/service-users

    The following response contains the APS ID of the user created earlier:

    HTTP/1.1 200 OK

[{"aps":{"id":"e21e19e0-5951-43a7-8103-8c5606398379",...},...},...]

  • APS ID of the silver offer that will be related with 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",...},...}]

  • APS ID of the management context that will be related with 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",...},...}]

  • APS ID of the subscription whose limits must allow creating 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 if there is a VPS with similar properties and if 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 if there is a VPS with the 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 if 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 Resource

A REST request for creating a new VPS must comply with the vps type investigated earlier. The most important is to 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:

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-user1.png

Conclusion

You have got experience in creating and managing customer administrators (staff members) and service users. Also, you have 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). For this aim, log in to PCP and navigate to System > Users to get 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 out the newly created VPS and examine the properties you have assigned to it.