Package com.ibm.soa.parlayx21.group

Address List Management.

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  
 

Package com.ibm.soa.parlayx21.group Description

Address List Management.

Common Data Types

For common data types associated with this package see Common Data Types.

Scope

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.

References

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

Definitions and abbreviations

Definitions

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

Abbreviations

For the purposes of the present document, the abbreviations defined in ES 202 391-1 [2] apply.

Detailed service description

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.

Group URI format

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.

Address list usage in services

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.

Namespaces

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.

Sequence diagrams

Manage groups (Create, delete, query, set access and query access)

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.

Figure 1

Manage Group Members (AddMember, AddMembers, DeleteMember, DeleteMembers, QueryMembers)

Pattern: Request / Response.

The group membership functions are shown in this diagram, showing the two add, two delete, and the query function.

Figure 2

XML Schema data type definition

AccessPermissions structure

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

AttributeStatus enumeration


Valid Attribute is valid
Unknown Attribute is not defined
Denied Access to the attribute is denied.

SimpleAttribute structure

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

Web Service interface definition

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.

Fault definitions

PolicyException

POL0210: Too many members in group

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

POL0211: Subgroups not supported

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

POL0212: Group name too long

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

POL0213: Group already exists

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

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



Copyright © 2003 IBM Corp. All Rights Reserved.