|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
---|---|
Group | The Group interface provides the administration interface for creating, deleting, querying members within a group. |
Group_RI | |
GroupHome | |
GroupService |
Class Summary | |
---|---|
AccessPermissions | List of access permissions that may be assigned to a requester associated with a group. |
AccessPermissions_Deser | |
AccessPermissions_Helper | |
AccessPermissions_Ser | |
AttributeStatus | |
GroupBindingStub | |
GroupProxy | |
GroupServiceInformation | |
GroupServiceLocator | |
SimpleAttribute | Attribute representing a name and an associated value. |
SimpleAttribute_Deser | |
SimpleAttribute_Helper | |
SimpleAttribute_Ser |
Address List Management.
The present document is part 13 of the Stage 3 Parlay X 2 Web Services specification for Open Service Access (OSA).
The OSA specifications define an architecture that enables application developers to make use of network functionality through an open standardized interface, i.e. the OSA APIs.
The present document specifies the Address List Management Web Service. The following are defined here:
* Name spaces.
* Sequence diagrams.
* Data definitions.
* Interface specification plus detailed method descriptions.
* Fault definitions.
* Service Policies.
* WSDL Description of the interfaces.
The following documents contain provisions which, through reference in this text, constitute provisions of the present document.
* References are either specific (identified by date of publication and/or edition number or version number) or nonspecific.
* For a specific reference, subsequent revisions do not apply.
* For a non-specific reference, the latest version applies.
Referenced documents which are not found to be publicly available in the expected location might be found at http://docbox.etsi.org/Reference.
[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
[2] ETSI ES 202 391-1: "Open Service Access (OSA); Parlay X 2 Web Services; Part 1: Common".
[3] IETF RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax".
For the purposes of the present document, the terms and definitions given in ES 202 391-1 [2] and the following apply: application managed group: group created and managed outside of the network, requiring the group members to be passed into the network for processing group: container for a set of addresses, it is not an address itself. When a group contain one or more groups, logically the group contains the set of addresses it holds, plus the set of addresses that any contained group holds (including any addresses contained in groups that a contained group holds) group resolution: when a group is processed by a service, it expands the group (and any nested groups) into a set of addresses. The resulting set of addresses contains no groups, and any duplicate addresses are removed. Thus, a resolved group may be considered an exclusive union of all of its contained members network managed group: group created and managed within a network, allowing Web Services to reference the members of a group using the group name
For the purposes of the present document, the abbreviations defined in ES 202 391-1 [2] apply.
The present document defines two related interfaces, one to manage the groups themselves - creation, deletion, query and access right management. The second interface manages the members within a group, supporting add, delete and query operations.
Addresses are not created using this service, they must already exist.
A group URI is consistent with the style defined in RFC 2396 [3], supporting the following URI style which is used in schemes such as sip and mailto: scheme:dept1294@mydivision.mycompany.serviceprovider.com
The group URI consists of the following discrete elements:
Scheme: selected by the provider of the group URI.
Group name: following the conventions of RFC 2396 [3].
Suffix: may be added by Service Provider (if allowed by creation operation) to create a unique name when the Prefix + Group name already exists.
Sub-domain: defined by the requester, this is contained within the domain provided by the service provider.
Domain: defined by the Service Provider, and cannot be specified by the application.
This definition of a group URI enables flexibility on the part of the Service Provider and the Requester, while ensuring unique groups are created and providing transparency of implementation of group storage.
The following are some group URI examples.
* sip:salesteam@sales.acme.anytelco.com
* sip:salesteam1@sales.acme.anytelco.com
* mailto:fieldservice@cityofaustin.anytelco.com
* group:mailroom@bldg001.acme.anytelco.com
These examples show (1)(2) use of prefix to create unique names, (1)(3) use of different defined schemes, and (4) use of a service provider defined scheme.
When a service has a requirement to support groups of address lists, it may satisfy this requirement by utilizing network managed groups. The group URI is passed to the service, and this group URI is resolved to the set of URIs contained within the group. If one or more group URIs are provided in a set of URIs to a service, the service will replace each group URI with its set of contained URIs, and the service processing will apply to the unique union of URIs generated.
If supported by the service policy, zero or more of the set of URIs contained within a group may be themselves group URIs, which would also be resolved. Thus, in this case, the list of URIs that the service would process would be the union of individual URIs (as a set with no duplicates).
Unless specifically defined in the semantics of a service, the expected semantic for the results of a service operation will be presented as the results for the set of URIs as processed (the union of non-group and group provided URIs), without group URIs included in the result. This eliminates a variety of complexity issues including duplicate URIs in multiple groups and the differences between a group URI and a URI referring to an endpoint.
The GroupManagement interface uses the namespace: http://www.csapi.org/wsdl/parlayx/group_mgmt/v2_1
The Group interface uses the namespace: http://www.csapi.org/wsdl/parlayx/group/v2_1
The GroupMember interface uses the namespace: http://www.csapi.org/wsdl/parlayx/group_member/v2_1
The data types are defined in the namespace: http://www.csapi.org/schema/parlayx/group/v2_1
The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema [1]. The use of the name 'xsd' is not semantically significant.
Pattern: Request / Response.
The group management functions are shown in this diagram, showing a sequence including the creation of a group, setting access permissions to the group, querying those permissions, query of groups and finally deletion of a group.
Pattern: Request / Response.
The group membership functions are shown in this diagram, showing the two add, two delete, and the query function.
List of access permissions that may be assigned to a requester associated with a group.
adminPermission
xsd:boolean
Requester has admin permission for the group
addPermission
xsd:boolean
Requester can add members to a group
deletePermission
xsd:boolean
Requester can delete members from a group
queryPermission
xsd:boolean
Requester can query members in a group
Valid
Attribute is valid
Unknown
Attribute is not defined
Denied
Access to the attribute is denied.
Attribute representing a name and an associated value.
Name
xsd:string
Name of the attribute
Type
xsd:string
Type of the attribute. The value is always a string, but this provides information on the format of the value
value
xsd:string
Value of the attribute
status
AttributeStatus
Status of the attribute
The Address List Management service consists of three interfaces:
* GroupManagement which manages creation and access to groups that hold the address lists.
* Group which manages the content of the address list.
* GroupMember which represents an address list entry and its associated properties.
Together these provide the interfaces to create and manage address lists, enabling these groups to be used by other services through this common capability.
Number of members in a group exceeds the number allowed by the Service Policy (MaxGroupMembers).
messageId
POL0210
text
Attempt to exceed maximum number of members in a group. Maximum number allowed is %1
variables
%1 = Maximum number allowed by Service Policy
Attempt to add a subgroup not permitted by Service Policy (SupportNestedGroups).
messageId
POL0211
text
Attempted to add a group to an existing group. Subgroups are not supported
variables
None
Length of group name exceeds the length allowed by the Service Policy (MaxGroupLength).
messageId
POL0212
text
Group name is too long. Maximum length allowed is %1
variables
%1 = Maximum length allowed by Service Policy
If the group name is not unique and the autoName part value is set to 'false', then a PolicyException is returned since the group name already exists.
messageId
POL0213
text
Group URI %1 already exists. Group not created
variables
%1 = Group URI
Service policies for this service.
MaxGroupLength
xsd:int
Maximum length of the group name (user portion)
MaxGroupMembers
xsd:int
Maximum number of members in a group
SupportNestedGroups
xsd:boolean
Can a group member be a group URI
|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |