Glossary Item Box

Government Gateway 2.2.0 (MR-01) ISV Developer Help (Doc Version 06/03/08) | Send comments on this topic.

# GatewaySoapPublic.GsoGetClientAllocationList Method

This method returns all of the client allocations for an agent group.

public void GsoGetClientAllocationList(
string inputXml,
out string outputXml
);

#### Parameters

inputXml
  Input Xml for this method must have the namespace urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlInput
outputXml
  Output Xml for this method must have the namespace urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlOutput

#### Remarks

The input parameter is an XML document that contains the following elements:

- ClientServiceName: The principal service to filter by
- AssignedTo: To return client allocations for the group, the caller or unassigned
- StartRecord: The first record to return
- MaxRecords: The number of records to return

The schema for the input document is as follows (this xsd references GsoCore.xsd):

    <?xml version="1.0" encoding="utf-8"?>
    <xs:schema targetNamespace="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlInput" xmlns="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlInput" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore" />
      <xs:element name="GsoGetClientAllocationListXmlInput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ClientServiceName" type="core:ServiceNameTYPE" />
            <xs:element name="AssignedTo">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:enumeration value="All" />
                  <xs:enumeration value="Me" />
                  <xs:enumeration value="Unassigned" />
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element name="StartRecord">
              <xs:simpleType>
                <xs:restriction base="xs:positiveInteger" />
              </xs:simpleType>
            </xs:element>
            <xs:element name="MaxRecords">
              <xs:simpleType>
                <xs:restriction base="xs:positiveInteger">
                  <xs:minInclusive value="10" />
                  <xs:maxInclusive value="1000" />
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>

The schema for the output document is as follows (this xsd references GsoCore.xsd):

    <?xml version="1.0" encoding="utf-8"?>
    <xs:schema targetNamespace="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlOutput" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlOutput" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore" />
      <xs:element name="GsoGetClientAllocationListXmlOutput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="StartRecord">
              <xs:simpleType>
                <xs:restriction base="xs:positiveInteger" />
              </xs:simpleType>
            </xs:element>
            <xs:element name="TotalRecords">
              <xs:simpleType>
                <xs:restriction base="xs:nonNegativeInteger" />
              </xs:simpleType>
            </xs:element>
            <xs:element name="ClientAllocations">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ClientAllocation" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="FriendlyName" type="core:EnrolmentFriendlyNameTYPE" />
                        <xs:element name="IdentifiersForDisplay">
                          <xs:complexType>
                            <xs:sequence>
                              <xs:element name="IdentifierForDisplay" type="core:IdentifierForDisplayTYPE" maxOccurs="unbounded" />
                            </xs:sequence>
                          </xs:complexType>
                        </xs:element>
                        <xs:element name="IsAssignedToMe" type="xs:boolean" />
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="RequestID" type="core:HashTokenTYPE" use="required" />
        </xs:complexType>
      </xs:element>
    </xs:schema>

#### Method Details

For the principal service identified by ClientServiceName this method returns:

- All the client allocations to the caller's agent group (if AssignedTo = "All")
- Only the client allocations (to the caller's agent group) that have not been assigned within the agent group (if AssignedTo = "Unassigned")
- Only the client allocations (to the caller's agent group) that are assigned to the caller (if AssignedTo = "Me")

StartRecord and MaxRecords provide control over the number of records returned, allowing between 10 and up to a maximum of 1000 records to be requested at a time. Note that the results are a snapshot of the records found at the moment the request was processed. It is possible the client allocation list is modified between requests.

StartRecord and TotalRecords identify the range of client allocations returned. Each Client Allocation includes the enrolment friendly name, the enrolment identifiers and whether the allocation is assigned to the agent calling credential (i.e. IsAssignedToMe is set to 1).

Note to see the client allocations for another credential (user or assistant) in the agent group, rather than for the calling credential, see GatewaySoapPublic.GsoGetAssignedClientAllocationsForAgentCredential.

#### Method Steps

This method performs the following steps:

- Checks the service exits and the service is of the right type
- Filters the records based on AssignedTo value
- Checks StartRecord is valid
- Returns the selected client allocations

#### Calling Credential

The credential calling the function must meet the following rules

Rule | Error
--- | ---
The Credential must present a 'Standard' GatewayToken | wsse:FailedAuthentication Presenting the incorrect token will produce the standard wsse:FailedAuthentication exception
The Credential must be the member of a Group | 8029: The Credential is not a member of an Organisation If the credential's registration category allows either peers or assistants then they are deemed to belong to an Organisation. This exception is raised when a Credential who does not belong to an Organisation attempts to call a method that controls Organisation specific functionality.
The Credential must of the following type: Agent | 8006: The Credential type specified is invalid Specific methods can only be performed for certain types of Credential (e.g. Principal, Agent, Admin etc.), if the supplied Credential is of the wrong type for the method then this exception will be raised.
The Credential's state must be: Active | 8005: The Credential has an invalid state for this action Each Credential has a number of states (e.g. Registered, Suspended), and specific methods require the Credential to be in a certain state. If the Credential is in the wrong state then this exception will be raised

#### Business Rules

All errors will return a SOAP fault. The GatewayDetails node will include ErrorNumber. It also contains a Message node with a detailed description of the cause of the error. The following is a list of the Error Numbers that may be returned from this method, each one represents a business rule that has been broken:

SOAP Fault Error Number | Description
--- | ---
3002 | The service specified does not exist The Service supplied to the method does not exist on the Gateway
3004 | The Service supplied is not of the correct type for this method This exception is thrown when a method is expected a Service of a specific type and has been passed something different. For example, if an Agent Service is supplied when trying to enrol in a Principal Service
7007 | ClientAllocationStartRecord exceeds total records The GetClientAllocationList start record specified may not exceed the total records identified by the call

#### Audit Events

Audit Events are stored in the Audit Database. These events are not available publicly. Please contact Live Services for more information

Audit ID | Description
--- | ---
506 | GsoAuthorisation (Failure)

#### Notifications

Notifications are messages that originate from the Gateway and sent to an external source.

Notification | Description
--- | ---

#### Example

The following is a sample of an input document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoGetClientAllocationListXmlInput xmlns="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlInput">
      <ClientServiceName>MOSW2</ClientServiceName>
      <AssignedTo>All</AssignedTo>
      <StartRecord>1</StartRecord>
      <MaxRecords>1000</MaxRecords>
    </GsoGetClientAllocationListXmlInput>

The following is a sample of an output document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoGetClientAllocationListXmlOutput RequestID="E2D27EB22435416BBCA924B3E1A12201" xmlns="urn:GSO-System-Services:external:1.65:GsoGetClientAllocationListXmlOutput">
      <StartRecord>1</StartRecord>
      <TotalRecords>2</TotalRecords>
      <ClientAllocations>
        <ClientAllocation>
          <FriendlyName/>
          <IdentifiersForDisplay>
            <IdentifierForDisplay Type="MOSW2ID" Value="1234569" MaskedValue="1*3*5*9" />
            <IdentifierForDisplay Type="MOSW2Number" Value="123" MaskedValue="1*3" />
          </IdentifiersForDisplay>
          <IsAssignedToMe>true</IsAssignedToMe>
        </ClientAllocation>
        <ClientAllocation>
          <FriendlyName/>
          <IdentifiersForDisplay>
            <IdentifierForDisplay Type="MOSW2ID" Value="1264656" MaskedValue="1*6*6*6" />
            <IdentifierForDisplay Type="MOSW2Number" Value="321" MaskedValue="3*1" />
          </IdentifiersForDisplay>
          <IsAssignedToMe>false</IsAssignedToMe>
        </ClientAllocation>
      </ClientAllocations>
    </GsoGetClientAllocationListXmlOutput>

#### See Also

Public Interface

© Crown Copyright 2008. All rights reserved