Cisco Unity Express -- User and Group Management REST PI Service Operation

From DocWiki

Revision as of 01:34, 3 May 2010 by Mnapalan (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Main page: Cisco Unity Express -- REST PI Service Operations

Previous page: Cisco Unity Express -- Common Base Classes REST PI Service Operation

Next page: Cisco Unity Express -- Mailbox REST PI Service Operation


Search the Cisco Unity Express documentation on the DocWiki:

Loading



Contents

User and Group Management

Classes

Figure 5: User and Group Management

CUE80 User and Group Management.jpg


User
Class Name

User

Extends From

ManagedBaseElement

Description

This class represents a subscriber in a CUE system.

XML Namespace

http://user.model.rest.aesop.cisco.com

Field Name Type Constraints Comments

userId

String

Required for POST (create) operation Length 2-31

Specifies the name or ID of the subscriber to be created. The username must be at least 3 and no more than 32 characters in length. CUE allows only letters, numbers, underscore (_), dot (.), and dash (-) in user IDs. User IDs must start with a letter. Do not use spaces in the username.

firstName

String

Length 0-59

First name of a user. Callers use these names to access the extension using the dial-by-name feature. Cannot contain special characters, spaces, or numbers.

lastName

String

Length 0-59

Last name of a user. Callers use these names to access the extension using the dial-by-name or numbers.

nickName

String

Length 0-59

displayName

String

Length 0-59

User's name displayed within CUE applications.

phoneNumberE164

String

Length 0-15

Full telephone number, including area code, for the subscriber.

phoneNumber

String

Length 0-15

Extension or number for this subscriber.

faxNumber

String

Length 0-15

password

String

Length 3-32

Password for the subscriber. Valid values contain at least 3 but not more than 32 characters in length. Spaces are not allowed. Acceptable password characters are lowercase letters a to z, uppercase letters A to Z, digits 0 to 9, and the following symbols: - , . + = _ ! @ # $ ^ * ( ) ? / ~ < > & %.

pin

String

Length 3 -16

Personal identification number for the subscriber. Valid values are at least 3 but not more than 19 characters in length, consisting of letters and numbers. No other characters are permitted.

language

String

Language locale string of the form xx_YY (where xx is the two letter language code and YY is the two letter country code).

Language of the prompts played to the user.

email

String

Length 0 - 320

Email address of the subscriber.

epage

String

Length 0 - 320

Epage address of the subscriber.

generateOptions

GenerateCredentialsOptions

For write only (To be used only during the POST and PUT operations).

Used for specifying options for generating password and pin during create and update operation.

spokenName

SpokenName

For Read only

This field indicates if a spoken name is configured for the user.


GenerateCredentialsOptions
Class Name

GenerateCredentialsOptions (Enumeration Class)

Extends From
Description

Enumeration class used specifying options for auto credential generation during user create and delete operations.

XML Namespace

http://user.model.rest.aesop.cisco.com

Enum Values

GenerateBlank, GenerateRandom, UserSpecified


Spoken Name
Class Name

SpokenName

Extends From

ManagedBaseElement

Description

This class represents the configured spoken name for a user. It does not define and fields locally and contains only the "resourceURI" field inherited from the parent class.

XML Namespace

http://user.model.rest.aesop.cisco.com


VmUser
Class Name

VmUser

Extends From

User

Description

This class represents voicemail subscribers in CUE system. It does not define and fields locally and inherits all its field from the base class "User".

XML Namespace

http://user.model.rest.voicemail.aesop.cisco.com


Group
Class Name

Group

Extends From

ManagedBaseElement

Description

Represents "groups" in CUE system. Usually created to manage privileges for a group of users.

XML Namespace

http://user.model.rest.aesop.cisco.com

Field Name Type Constraints Comments

groupId

String

Required for POST (create) operation Length 2-31

Name of the group.

description

String

Length 0-40

For providing a brief description about the group.

displayName

String

Length 0-59 If no value is specified during create, system will assign a value using groupId field value.

Full group name. Callers use the full name to access the extension using the dial-by-name feature.

email

String

Length 0 - 320

Email address of the group.

epage

String

Length 0 - 320

Epage address of the group.

privilege

Privilege

minOccurs="0" maxOccurs="unbounded"

Collection of privilege objects assigned to this group.

spokenName

SpokenName

For Read only

This field indicates if a spoken name is configured for the user.


VmGroup
Class Name

VmGroup

Extends From

Group

Description

Represents "groups" in CUE system. Usually created to manage privileges for a group of users and to assign members to a general-delivery mailbox. Inherits all the fields from base class "Group", as well as define local fields specific to voicemail-related features.

XML Namespace

http://user.model.rest.voicemail.aesop.cisco.com

Field Name Type Constraints Comments

faxNumber

String

Length 0 -15

Group fax number

phoneNumberE164

String

Length 0-15

Full telephone number, including area code for the group.

phoneNumber

String

Length 0-15

Primary extension for the group's general-delivery mailbox.

Resources

Resource URI Operation Input Return Value

/voicemail/users

GET (read all users)

BaseElementList containing "VmUser" objects.

POST create user)

VmUser

/voicemail/users/{userid}

GET (read a user)

VmUser

PUT (update a user)

VmUser

DELETE (delete user)

/voicemail/users/{userid}/groupmemberships

GET (read groups where this user is a member)

BaseElementList containing "VmGroup" objects

POST (add this user to a group as member)

VmGroup (Only Resource URI)

/voicemail/users/{userid}/groupmemberships/{groupid}

DELETE (remove this user from a group as member)

/voicemail/users/{userid}/groupownerships

GET (read groups where this user is an owner)

BaseElementList containing "VmGroup" objects

POST (add this user to a group as owner)

VmGroup (Only Resource URI)

/voicemail/users/{userid}/groupownerships/{groupid}

DELETE (remove this user as owner from a group)

/voicemail/users/{userid}/spokenname

GET (download spoken name for this user)

Accept: audio/x-wav

Audio wav file of spoken name for user

PUT (Upload audio wav file for spoken name for user)

Content-type: audio/x-wav

/voicemail/groups

GET (read all groups)

BaseElementList containing "VmGroup" objects

POST (create a new group)

VmGroup (including group's Privileges)

/voicemail/groups/{groupid}

PUT (update a group)

VmGroup (including group's Privileges)

GET (read a group)

VmGroup (including group's Privileges

DELETE (delete group)

/voicemail/groups/{groupid}/groupmemberships

GET (read groups where this group is a member)

BaseElementList containing "VmGroup" objects

POST (add the addressed group as member of another group)

VmGroup (Resource URI only)

/voicemail/groups/{groupid}/groupmemberships/{groupid}

DELETE (remove the addressed group as member from another group)

/voicemail/groups/{groupid}/groupownerships

GET (read groups where this group is an owner)

BaseElementList containing "VmGroup" objects

PUT (add the addressed group as member of another group)

VmGroup (Resource URI only)

/voicemail/groups/{groupid}/groupownerships/{groupid}

DELETE (remove the addressed group as owner of another group)

/voicemail/groups/{groupid}/members

GET (read all members of a group)

BaseElementList containing "VmGroup" and "VmUser" objects

POST (add a user or group as member to this group)

VmUser or VmGroup

/voicemail/groups/{groupid}/members/{memberId}

DELETE (remove a member from this group)

/voicemail/groups/{groupid}/owners

GET (read all owners of this group)

BaseElementList containing "VmGroup" and "VmUser" objects

POST (add a user or group as owner to this group)

VmUser or VmGroup

/voicemail/groups/{groupid}/owners/{ownerId}

DELETE (remove an owner from this group)

/voicemail/groups/{groupid}/privileges

GET (get list of privileges for this group)

BaseElementList containing "Privilege" objects

POST (Add a privilege to this group)

Privilege (with Resource URI or name) (to set multiple privileges for a group use update group operation)

/voicemail/groups/{groupid}/privileges/{privilegeName}

DELETE (Remove a privilege from this group)

/rest/groups/{groupid}/spokenname

GET (download spoken name for group)

Accept: audio/x-wav

Audio wav file of spoken name for user

PUT (Upload spoken name for group)

Content-type: audio/x-wav


User and Group Examples

Create User

Create a new user. Data for the new user is read from local file data/create_userx.xml. 

 $ cat data/create_userx.xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <vmUser>
      <displayName>Mr. X Yzee</displayName>
      <email>email_xyz@email.com</email>
      <epage>epage_xyz@address.com</epage>
      <firstName>Axe</firstName>
      <language>en_US</language>
      <lastName>Yzee</lastName>
      <nickName>xyz</nickName>
      <phoneNumber>1010</phoneNumber>
      <phoneNumberE164>213151273</phoneNumberE164>
      <pin>1234</pin>
      <generateOptions>
         <passwordOption>GenerateRandom</passwordOption>
      </generateOptions>
      <userId>userX</userId>
   </vmUser>

 $ curl -i -X POST -H 'Authorization: Basic Y2lzY286Y2lzY28=' -H 'Content-type: application/xml'  
 -d @./data/create_userx.xml http://172.27.104.144/rest/voicemail/users 
 
 HTTP/1.1 201 Created
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=CDE84ED1DFCC25FA7F8029EE0C27E755; Path=/rest
 PI-Version: 8.0.0.150
 Location: http://172.27.104.144/rest/voicemail/users/voicemail/users/userX 
 Content-Type: text/plain
 Transfer-Encoding: chunked
 Date: Fri, 04 Dec 2009 02:11:43 GMT
 Created - /voicemail/users/userX
Read All Users

Read all users. Specify only first name and lastName fields to be included in the results. 

 $ curl -i -X GET -H 'Authorization: Basic Y2lzY286Y2lzY28=' http://172.27.104.144/rest/voicemail 
 /users?fields=firstName,lastName

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=441971AE997CDD32051F45F1544A8231; Path=/rest
 PI-Version: 8.0.0.150
 Content-Type: application/xml
 Transfer-Encoding: chunked
 Date: Fri, 04 Dec 2009 02:03:00 GMT

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <baseElementList>
      <baseElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
 xmlns:ns3="http://user.model.rest.voicemail.aesop.cisco.com" xsi:type="ns3:vmUser">
         <resourceURI>/voicemail/users/userX</resourceURI>
         <firstName>Axe</firstName>
         <lastName>Yzee</lastName>
      </baseElement>
      <baseElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
 xmlns:ns3="http://user.model.rest.voicemail.aesop.cisco.com" xsi:type="ns3:vmUser">
         <resourceURI>/voicemail/users/cisco</resourceURI>
         <firstName>first</firstName>
         <lastName>cisco</lastName>
      </baseElement>
 </baseElementList>
Create Group

Create a Group. Data for the new group is read from local file ./data/create_groupy.xml. 

 $ cat data/create_groupy.xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <vmGroup>
    <description>GroupY</description>
    <displayName>GroupWhy</displayName>
    <email>email@noreply.com</email>
    <groupId>groupY</groupId>
    <language>en_US</language>
    <privilege>
         <resourceURI>/privileges/tcv-payroll</resourceURI>
    </privilege>
    <privilege>
         <name>ViewHistoricalReports</name>
    </privilege>
    <privilege>
         <name>ManagePublicList</name>
    </privilege>
    <privilege>
         <resourceURI>/privileges/ManagePrompts</resourceURI>
    </privilege>
 </vmGroup>

 $ curl -i -X POST -H 'Authorization: Basic Y2lzY286Y2lzY28=' -H 'Content-type: application/xml'  
 -d @./data/create_groupy.xml http://172.27.104.144/rest/voicemail/groups 
 HTTP/1.1 201 Created
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=3B975C8500C143DB10E47B4970DDB2C0; Path=/rest
 PI-Version: 8.0.0.150
 Location: http://172.27.104.144/rest/voicemail/groups/voicemail/groups/groupY 
 Content-Type: text/plain
 Transfer-Encoding: chunked
 Date: Fri, 04 Dec 2009 06:15:16 GMT
 Created - /voicemail/groups/groupY
Add User to a Group

Add userX as member to groupY. Input data is read from local file ./data/userx.xml. 

$ cat ./data/userx.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vmUser>
     <userId>userX</userId>
</vmUser>

$ curl -i -X POST -H 'Authorization: Basic Y2lzY286Y2lzY28=' -H 'Content-type: application/xml'  
-d  @./data/userx.xml 
http://172.27.104.144/rest/voicemail/groups/groupY/members 

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=58D138AD5DE9ECCBD801D86F0518755C; Path=/rest
PI-Version: 8.0.0.150
Content-Type: text/plain
Transfer-Encoding: chunked
Date: Fri, 04 Dec 2009 06:22:57 GMT

Added userX as member to Group - groupY
Remove User from a Group

Remove userX as member of groupY. 

$ curl -i -X DELETE -H 'Authorization: Basic Y2lzY286Y2lzY28=' 
http://172.27.104.144/rest/voicemail/groups/groupY/members/userX 

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=C182CA0E8CF34573508C6D31E99DA6A4; Path=/rest
PI-Version: 8.0.0.150
Content-Type: text/plain
Transfer-Encoding: chunked
Date: Fri, 04 Dec 2009 06:34:46 GMT

Removed userX as member of Group - groupY
Upload Spoken Name for Group

Upload spoken name for groupX. The spoken name is uploaded from local wav file data/groupX.upload.wav 

$ curl -i -T ./data/groupX.upload.wav -H 'Authorization: Basic Y2lzY286Y2lzY28=' -H  
'Content-type: audio/x-wav' 
http://172.27.104.144/rest/voicemail/groups/groupX/spokenname 
HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=6EDB5242A677B1CD6495DD96A2D5D256; Path=/rest
PI-Version: 8.0.0.150
Content-Type: text/plain
Transfer-Encoding: chunked
Date: Fri, 04 Dec 2009 06:38:50 GMT

Uploaded - /voicemail/groups/groupX/spokenname

$ curl -i -X GET -H 'Authorization: Basic Y2lzY286Y2lzY28=' 
http://172.27.104.144/rest/voicemail/groups/groupX 
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=A98FDBA862CD2DFAC7DE079ACE304678; Path=/rest
PI-Version: 8.0.0.150
Content-Type: application/xml
Content-Length: 488
Date: Fri, 04 Dec 2009 06:42:44 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vmGroup>
     <resourceURI>/voicemail/groups/groupX</resourceURI>
     <description>Group X's Description</description>
     <displayName>Group Hacks</displayName>
     <email>email@noreply.com</email>
     <groupId>groupX</groupId>
     <language>en_US</language>
     <spokenName>
          <resourceURI>/voicemail/groups/groupX/spokenname</resourceURI>
     </spokenName>
      <faxNumber>56908762</faxNumber>
      <phoneNumber>7654</phoneNumber>
      <phoneNumberE164>4083925174</phoneNumberE164>
</vmGroup>

Rating: 0.0/5 (0 votes cast)

Retrieved from "http://docwiki.cisco.com/wiki/Cisco_Unity_Express_--_User_and_Group_Management_REST_PI_Service_Operation"
Personal tools